# https://github.com/devflowinc/trieve Project Manual Generated at: 2026-06-25 06:30:12 UTC ## Table of Contents - [Overview and System Architecture](#page-1) - [Backend Server, Handlers, and Workers](#page-2) - [Frontend Applications, Search Component, and Client SDKs](#page-3) - [Deployment, Infrastructure, and Sidecar Services](#page-4) ## Overview and System Architecture ### Related Pages Related topics: [Backend Server, Handlers, and Workers](#page-2), [Frontend Applications, Search Component, and Client SDKs](#page-3), [Deployment, Infrastructure, and Sidecar Services](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/devflowinc/trieve/blob/main/README.md) - [website/README.md](https://github.com/devflowinc/trieve/blob/main/website/README.md) - [website/package.json](https://github.com/devflowinc/trieve/blob/main/website/package.json) - [website/src/content/products/trieve-api/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml) - [website/src/content/singles/homepage/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/homepage/index.yaml) - [website/src/content/singles/resources-megamenu/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/resources-megamenu/index.yaml) - [website/src/content/integrations/judge-me/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/integrations/judge-me/index.yaml) - [website/src/lib/keystatic/collections/pages.ts](https://github.com/devflowinc/trieve/blob/main/website/src/lib/keystatic/collections/pages.ts) - [website/src/pages/rss.xml.js](https://github.com/devflowinc/trieve/blob/main/website/src/pages/rss.xml.js) - [clients/mcp-server/package.json](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json) - [clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md) - [clients/docusaurus-theme-search/package.json](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json) - [frontends/chat/package.json](https://github.com/devflowinc/trieve/blob/main/frontends/chat/package.json) - [frontends/chat/src/utils/apiTypes.ts](https://github.com/devflowinc/trieve/blob/main/frontends/chat/src/utils/apiTypes.ts)
# Overview and System Architecture ## Purpose and Scope Trieve is an end-to-end, open-source infrastructure layer for AI-powered discovery experiences, exposing a single REST surface that combines semantic vector search, typo-tolerant sparse retrieval, recommendations, and managed Retrieval-Augmented Generation (RAG). Per the project README, the platform is designed so that "All of the functionality within Trieve is also exposed via API. LLM completions, tool calls, image generation, search, memory, and more all behind one well-designed REST surface" ([website/src/content/products/trieve-api/index.yaml:hero.description](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml)). The repository is a monorepo that bundles the backend server, multiple frontend applications, client SDKs, MCP/automation integrations, a documentation theme, and a marketing website. The headline value proposition is a 72-endpoint API that productionizes hybrid search, BM25/SPLADE sparse retrieval, BGE cross-encoder re-ranking, and OpenRouter-backed RAG behind a single developer surface ([README.md:Features](https://github.com/devflowinc/trieve/blob/main/README.md)). ## Core System Components The codebase is organized into several top-level directories that each play a distinct role in the overall system: | Directory | Role | Notes | | :--- | :--- | :--- | | `server/` | Core API service (Rust, inferred from README feature claims) | Hosts the 72 REST endpoints and orchestrates embedding, sparse-vector, and LLM calls. | | `frontends/chat/` | Solid.js-based demo chat UI | Depends on `trieve-ts-sdk` and `shared` workspace packages ([frontends/chat/package.json:dependencies](https://github.com/devflowinc/trieve/blob/main/frontends/chat/package.json)). | | `clients/search-component/` | Embeddable JS search widget | Currently ships ESM only; community issue #3157 tracks adding CommonJS output. | | `clients/ts-sdk/` & `clients/python-sdk/` | First-party client libraries | Surfaced as `trieve-ts-sdk` and `trieve-py-client` on npm and PyPI respectively. | | `clients/mcp-server/` | Model Context Protocol server | Keywords list model-context-protocol integration ([clients/mcp-server/package.json:keywords](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json)). | | `clients/n8n-nodes-trieve/` | n8n workflow integration | Exposes Chunk search, recommendations, and tool-call operations ([clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md)). | | `clients/docusaurus-theme-search/` | Drop-in Docusaurus search theme | Peer-depends on React 17–19 ([clients/docusaurus-theme-search/package.json:peerDependencies](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json)). | | `charts/trieve/` | Helm chart for self-hosted deployments | Latest published release is `trieve-helm-0.2.2` (community context). | | `website/` | Marketing site and blog | Astro + Tailwind + Keystatic CMS ([website/README.md](https://github.com/devflowinc/trieve/blob/main/website/README.md)). | ## Data Flow and Runtime Architecture At runtime, a Trieve deployment wires together an embedding model, a SPLADE sparse encoder, a Qdrant vector store, an optional cross-encoder re-ranker, and an LLM provider routed through OpenRouter. The README explicitly identifies these as the pluggable building blocks ("Bring Your Own Models") and notes the hybrid retrieval path uses `naver/efficient-splade-VI-BT-large-query` for sparse vectors and `BAAI/bge-reranker-large` for re-ranking ([README.md:Features](https://github.com/devflowinc/trieve/blob/main/README.md)). ```mermaid flowchart LR Client[SDK / UI / MCP / n8n] --> API[Trieve REST API] API --> Embed[Embedding Model] API --> Sparse[SPLADE Sparse Encoder] API --> Store[(Qdrant Vector Store)] API --> Rerank[BGE Cross-Encoder] API --> LLM[OpenRouter LLM] LLM --> API --> Client Store --> Rerank --> API ``` The chat frontend consumes the API through `trieve-ts-sdk` and operates on strongly typed DTOs such as `ChunkMetadata`, `FileDTO`, and `FileUploadCompleteNotificationDTO`, which are guarded by runtime type predicates like `isChunkMetadata` to defend against malformed API responses ([frontends/chat/src/utils/apiTypes.ts](https://github.com/devflowinc/trieve/blob/main/frontends/chat/src/utils/apiTypes.ts)). ## Deployment, Self-Hosting, and Ecosystem Trieve supports three deployment postures: a fully managed cloud service, a self-hosted Docker Compose stack, and a Helm-based Kubernetes distribution. The Helm chart is tracked independently and the most recent release, `trieve-helm-0.2.2`, ships the chart "without any dependencies," reflecting a deliberate split between the application chart and the database layer so they can be provisioned separately (community context: issue #2181, "tracking: glasskube package"). The marketing site uses Keystatic CMS collections defined in TypeScript. For example, the `pages` collection combines `metadata`, `pageHeader`, and `contentBlocks` blocks into a schema-driven authoring experience ([website/src/lib/keystatic/collections/pages.ts](https://github.com/devflowinc/trieve/blob/main/website/src/lib/keystatic/collections/pages.ts)). An RSS feed is generated from the `blogPosts` collection at build time ([website/src/pages/rss.xml.js](https://github.com/devflowinc/trieve/blob/main/website/src/pages/rss.xml.js)). ## Community-Driven Roadmap Several open issues illustrate the architecture's evolution. Issue #3157 calls for CommonJS output in `clients/search-component/scripts/build.js` so the embeddable search widget can be consumed outside modern bundlers. Issue #2957 highlights a correctness gap in the `create_chunk` handler, which today returns the raw request payload even when duplicate `tracking_id` values cause fewer chunks to actually be inserted. Issue #2758 tracks the completion of a demo UI that converts PDFs to Markdown via vision LLMs (e.g., GPT-4o) and renders a split-pane preview. Issue #2623 requests a batch group-deletion endpoint to avoid multiple round-trips when purging many groups at once. Together these signal an ongoing investment in developer ergonomics, batch APIs, and richer ingestion tooling layered on top of the core retrieval engine. ## See Also - Trieve API Reference (external): [https://docs.trieve.ai/api-reference](https://docs.trieve.ai/api-reference) - TypeScript SDK documentation: [https://ts-sdk.trieve.ai](https://ts-sdk.trieve.ai/) - Python SDK on PyPI: [https://pypi.org/project/trieve-py-client/](https://pypi.org/project/trieve-py-client/) - Self-hosting guides: [https://docs.trieve.ai/self-hosting/docker-compose](https://docs.trieve.ai/self-hosting/docker-compose) --- ## Backend Server, Handlers, and Workers ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Frontend Applications, Search Component, and Client SDKs](#page-3), [Deployment, Infrastructure, and Sidecar Services](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/devflowinc/trieve/blob/main/README.md) - [website/README.md](https://github.com/devflowinc/trieve/blob/main/website/README.md) - [website/package.json](https://github.com/devflowinc/trieve/blob/main/website/package.json) - [clients/mcp-server/README.md](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/README.md) - [clients/mcp-server/package.json](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json) - [clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md) - [frontends/chat/package.json](https://github.com/devflowinc/trieve/blob/main/frontends/chat/package.json) - [website/src/content/products/trieve-api/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml) - [website/src/content/singles/homepage/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/homepage/index.yaml) - [website/src/lib/keystatic/collections/pages.ts](https://github.com/devflowinc/trieve/blob/main/website/src/lib/keystatic/collections/pages.ts) > **Note on scope:** This page is bounded by the source files actually present in the retrieval context. The Rust handler and operator modules under `server/src/handlers/` and `server/src/operators/` are referenced by repository path (e.g., `chunk_handler.rs`, `group_handler.rs`, `search_operator.rs`, `qdrant_operator.rs`, `clickhouse_operator.rs`) and by open community issues, but their raw source was not included in this retrieval window. Where behavior is described from those modules, the supporting evidence comes from the README, SDK/MCP clients, and the linked community issues.
# Backend Server, Handlers, and Workers ## 1. Purpose and Role in the Trieve Stack Trieve is a hybrid retrieval and RAG platform whose central artifact is a single REST API exposing ~72 endpoints that cover ingestion, search, recommendation, chunk/group management, message-based RAG, and analytics. The backend server is the component that implements this API and coordinates the data stores behind it. Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md) (feature list at the top of the file describes the search, RAG, recommendation, and grouping capabilities that the server implements). Source: [website/src/content/products/trieve-api/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml) (describes the server as a "72-endpoint end-to-end platform" with a "Hybrid Retrieval Engine", "Managed RAG & Chat Endpoints", and "Flexible ETL & Tuning Pipeline"). The backend is intentionally the single source of truth that every client — web frontends, SDKs, the MCP server, the n8n node, the Shopify extension — talks to. As [website/src/content/singles/homepage/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/homepage/index.yaml) puts it, Trieve provides an "Athletic API" of 72 endpoints. Clients are thin wrappers around that API. Source: [website/src/content/singles/homepage/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/homepage/index.yaml). ## 2. Handler Layer: REST Endpoint Surface The handler layer is the HTTP boundary. Each handler module under `server/src/handlers/` maps to a resource family exposed by the API. The community issue tracker repeatedly refers to specific handlers by name, which is the cleanest evidence of their responsibilities: | Handler module | Resource family | Evidence | | --- | --- | --- | | `chunk_handler.rs` | Ingestion, update, delete, and retrieval of individual chunks; dedup by `tracking_id` | Issue #2957 ("dedup by `tracking_id` in the `create_chunk` handler") | | `group_handler.rs` | File-level grouping, batch operations on groups | Issue #2623 ("batch delete groups endpoint", targeting `server` and the `groups` route) | | `search_operator.rs` (handler) | Search query parsing, filter validation, hybrid search orchestration | Referenced in the standard handlers/operators split | | Message / completion handlers | RAG completions and topic-based memory | README links to `create_message_completion_handler` and `generate_off_chunks` | Source: community issues #2957 and #2623 referenced in the prompt. Two recurring handler concerns show up in community discussion: 1. **Return-shape fidelity.** The `create_chunk` handler currently echoes the request body back; when duplicates collapse in the DB, the response no longer matches the request (issue #2957). This is the kind of correctness bug that only shows up when handlers are wired into a write path that goes through a deduplicating operator. 2. **Batching round-trips.** Issue #2623 asks for a single batch-delete-groups endpoint to avoid multiple round-trips when deleting by `tracking_ids` or `group_ids`, with an option to also delete the underlying chunks. That implies the existing group delete is one-resource-per-call. Source: community issues #2957 and #2623 referenced in the prompt. ## 3. Operator Layer: Storage and Search Coordination Beneath the handlers sits an operator layer that isolates external systems. The naming convention in the repository (e.g., `qdrant_operator.rs`, `clickhouse_operator.rs`) and the README's storage descriptions make the division clear: ```mermaid flowchart LR Client[Client SDK / MCP / n8n] -->|HTTP| Handlers[handlers/*] Handlers --> Ops[operators/*] Ops --> Qdrant[(Qdrant: dense + SPLADE vectors)] Ops --> CH[(ClickHouse: analytics + events)] Ops --> BM25[(BM25 full-text)] Ops --> LLM[OpenRouter / BYO LLM] ``` Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md) — explicitly names Qdrant, SPLADE, and "Bring Your Own Models" for embeddings, SPLADE, cross-encoder re-ranking, and LLMs. The `search_operator` is the orchestrator: per the README it is responsible for hybrid search (BM25 + SPLADE + dense vectors), cross-encoder re-ranking with BAAI/bge-reranker-large, recency biasing, merchandizing signals, and filtering by date, substring, tag, and numeric predicates. Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md) (feature bullets covering hybrid search, recency biasing, merchandizing, and filtering). The `qdrant_operator` owns the vector store contract: chunk upsert, delete, and recommendation (similar-chunk) queries. Qdrant is named directly in the README as the backing store for semantic vector search. Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md). The `clickhouse_operator` owns event-style data: clicks, add-to-carts, citations, and analytics. The merchandizing feature ("tune relevance using signals like clicks, add-to-carts, or citations") requires an event store with high write throughput, which is consistent with ClickHouse's role. Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md). ## 4. Workers, Jobs, and Background Processing Several Trieve features cannot complete synchronously inside a single HTTP request and are therefore modeled as background workers: - **Embedding and SPLADE vectorization.** The README states "every uploaded chunk is vector'ized" with both a dense embedding model and `naver/efficient-splade-VI-BT-large-query`. Producing both vectors is too expensive for a tight request loop, so a worker pattern is implied. Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md). - **PDF → Markdown via vision LLMs.** Issue #2758 documents a demo UI for `pdf2md` powered by GPT-4o. Vision-LLM extraction is a long-running job that must be offloaded. Source: community issue #2758 referenced in the prompt. - **Native crawler and ETL pipeline.** The API product page describes an ETL pipeline that "splits, embeds, weights, and indexes" uploads with "filters, tag boosts, and weight multipliers." Source: [website/src/content/products/trieve-api/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml). - **Recency and event aggregation.** Recency biasing and merchandizing signals are only meaningful when computed against accumulated interaction data, which a background aggregator produces. Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md). ## 5. Client Surfaces That Consume the Backend The handler/operator/worker pipeline is exercised through several first-party clients, all of which are configured in this repo and consume `trieve-ts-sdk` or call the REST API directly: - **`trieve-ts-sdk`** — the generated TypeScript SDK used by the website (`website/package.json` pins `trieve-ts-sdk ^0.0.115`) and by the chat frontend (`frontends/chat/package.json` lists `"trieve-ts-sdk": "*"`). Source: [website/package.json](https://github.com/devflowinc/trieve/blob/main/website/package.json), [frontends/chat/package.json](https://github.com/devflowinc/trieve/blob/main/frontends/chat/package.json). - **MCP server** (`clients/mcp-server`) — exposes Trieve search and dataset listing as Model Context Protocol tools for AI agents, configured by `TRIEVE_API_KEY`, `TRIEVE_ORGANIZATION_ID`, and optionally `TRIEVE_DATASET_ID`. Source: [clients/mcp-server/README.md](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/README.md), [clients/mcp-server/package.json](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json). - **n8n node** (`clients/n8n-nodes-trieve`) — exposes operations like `tool_call` for parameter extraction; installed via `~/.n8n/custom/` symlink. Source: [clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md). - **Docusaurus search theme** and **Shopify extension** — additional consumer clients that embed Trieve search into documentation sites and storefronts. Source: [clients/docusaurus-theme-search/package.json](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json), [clients/trieve-shopify-extension/package.json](https://github.com/devflowinc/trieve/blob/main/clients/trieve-shopify-extension/package.json). ## 6. Operational Concerns and Known Failure Modes Two operational topics are visible from the community context: - **Build output for the search-component client.** Issue #3157 reports that the search-component client only emits ES modules and asks for a CommonJS build path, including updating the `package.json` scripts that push a beta build to the CDN. This is a packaging failure mode that affects consumers using CJS toolchains. Source: community issue #3157 referenced in the prompt. - **Helm chart maturity.** The latest published release is `trieve-helm-0.2.2` ("Helm chart expressing Trieve deployment without any dependencies"). Issue #2181 tracks a migration from Helm-managed databases to Glasskube packages, including a refactor to remove the database from the chart. This is the most direct evidence that the backend's deployable unit is being simplified toward an externally-provisioned data tier. Source: community issue #2181 referenced in the prompt, and the release note in the prompt context. ## 7. Summary The Trieve backend is a Rust-based REST server organized as **handlers → operators → external systems (Qdrant, ClickHouse, BM25 index, LLM providers)**, with background workers for embedding, SPLADE vectorization, PDF→Markdown extraction, and event aggregation. Handlers are the contract surface (chunk, group, search, message, completion), operators isolate the storage backends, and workers handle long-running or high-throughput tasks. Clients — the TypeScript SDK, the MCP server, the n8n node, the Docusaurus theme, and the Shopify extension — are all thin adapters to that single REST API. Known gaps in the current implementation, surfaced by community issues, include chunk-dedup accuracy in `create_chunk` (issue #2957), lack of a batch delete-groups endpoint (issue #2623), CJS build output for the search-component (issue #3157), and Helm chart cleanup toward Glasskube (issue #2181). ## See Also - [README.md](https://github.com/devflowinc/trieve/blob/main/README.md) — full feature list and SDK links - [website/src/content/products/trieve-api/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml) — product-level description of the API surface - [clients/mcp-server/README.md](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/README.md) — MCP server client surface - [clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md) — n8n integration node - [website/README.md](https://github.com/devflowinc/trieve/blob/main/website/README.md) — website/Astro project structure --- ## Frontend Applications, Search Component, and Client SDKs ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Backend Server, Handlers, and Workers](#page-2), [Deployment, Infrastructure, and Sidecar Services](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/devflowinc/trieve/blob/main/README.md) - [clients/search-component/scripts/build.js](https://github.com/devflowinc/trieve/blob/main/clients/search-component/scripts/build.js) - [clients/search-component/src/index.tsx](https://github.com/devflowinc/trieve/blob/main/clients/search-component/src/index.tsx) - [clients/search-component/src/TrieveModal/ModalContainer.tsx](https://github.com/devflowinc/trieve/blob/main/clients/search-component/src/TrieveModal/ModalContainer.tsx) - [clients/search-component/src/recommendations/Recommendations.tsx](https://github.com/devflowinc/trieve/blob/main/clients/search-component/src/recommendations/Recommendations.tsx) - [clients/ts-sdk/src/sdk.ts](https://github.com/devflowinc/trieve/blob/main/clients/ts-sdk/src/sdk.ts) - [clients/python-sdk/trieve_py_client/api_client.py](https://github.com/devflowinc/trieve/blob/main/clients/python-sdk/trieve_py_client/api_client.py) - [clients/mcp-server/package.json](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json) - [clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md) - [clients/docusaurus-theme-search/README.md](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/README.md) - [clients/docusaurus-theme-search/package.json](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json) - [frontends/chat/src/utils/apiTypes.ts](https://github.com/devflowinc/trieve/blob/main/frontends/chat/src/utils/apiTypes.ts) - [frontends/chat/src/index.css](https://github.com/devflowinc/trieve/blob/main/frontends/chat/src/index.css) - [website/README.md](https://github.com/devflowinc/trieve/blob/main/website/README.md) - [website/package.json](https://github.com/devflowinc/trieve/blob/main/website/package.json) - [website/src/pages/rss.xml.js](https://github.com/devflowinc/trieve/blob/main/website/src/pages/rss.xml.js) - [website/src/lib/keystatic/collections/pages.ts](https://github.com/devflowinc/trieve/blob/main/website/src/lib/keystatic/collections/pages.ts) - [website/src/content/products/trieve-api/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml) - [website/src/content/products/sitesearch/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/sitesearch/index.yaml) - [website/src/content/integrations/judge-me/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/integrations/judge-me/index.yaml) - [website/src/content/singles/homepage/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/homepage/index.yaml)
# Frontend Applications, Search Component, and Client SDKs ## Overview Trieve ships a complete user-facing layer on top of its hybrid search and RAG API. The `frontends/`, `clients/`, and `website/` directories together deliver a React-based chat reference application, a drop-in embeddable search component, several language-specific client SDKs, automation and documentation integrations, and the Astro marketing website. These surfaces let teams either self-host the full stack or embed Trieve into an existing product. The repository README describes a 72-endpoint API exposing semantic dense-vector search, typo-tolerant SPLADE sparse search, sub-sentence highlighting, recommendations, and managed RAG routes ([README.md](https://github.com/devflowinc/trieve/blob/main/README.md)). All of those capabilities are surfaced through the front-end artifacts described in the sections that follow. ## Frontend Applications ### Chat Reference Frontend The reference chat application lives under `frontends/chat/` and is built with React, TypeScript, and Tailwind CSS. API contracts are defined in [frontends/chat/src/utils/apiTypes.ts](https://github.com/devflowinc/trieve/blob/main/frontends/chat/src/utils/apiTypes.ts), which declares discriminated unions such as `ChunkCollectionSearchDTO`, `ChunkCollectionBookmarksDTO`, `CreateChunkDTO`, `FileDTO`, and `FileUploadCompleteNotificationDTO`. The exported `isChunkCollectionSearchDTO` type guard validates that `bookmarks`, `collection`, and `total_pages` are present and well-typed before narrowing the result. Search-result highlighting is rendered through CSS rules in [frontends/chat/src/index.css](https://github.com/devflowinc/trieve/blob/main/frontends/chat/src/index.css), where selectors like `#scoreChunk mark` and `#scoreChunk b > mark > *` apply a `#fffebd` background to bold the matching sub-sentences returned by Trieve's `simsearch`-based highlighter. ### Marketing and Documentation Website The public website is an Astro project under `website/`, configured with Tailwind CSS, TypeScript, and Keystatic CMS ([website/README.md](https://github.com/devflowinc/trieve/blob/main/website/README.md)). Pages are modelled as Keystatic collections in [website/src/lib/keystatic/collections/pages.ts](https://github.com/devflowinc/trieve/blob/main/website/src/lib/keystatic/collections/pages.ts), with a slug-based `title` field and schema composed from shared `metadata`, `pageHeader`, and `contentBlocks` field groups. The site publishes an RSS feed from [website/src/pages/rss.xml.js](https://github.com/devflowinc/trieve/blob/main/website/src/pages/rss.xml.js), which filters out drafts, sorts posts by `lastUpdatedAt`, and sanitises rendered Markdown with `sanitize-html` before emitting `en-us` as custom data. Product pages are stored as Keystatic singletons such as [website/src/content/products/trieve-api/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml) and [website/src/content/products/sitesearch/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/sitesearch/index.yaml); integrations such as Judge.me are stored similarly under [website/src/content/integrations/judge-me/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/integrations/judge-me/index.yaml). ## Embeddable Search Component The search component under `clients/search-component/` is a React widget that mounts into any host page. It exposes a `TrieveModal` root via [clients/search-component/src/index.tsx](https://github.com/devflowinc/trieve/blob/main/clients/search-component/src/index.tsx) and `ModalContainer.tsx`, and renders the recommendations experience through [clients/search-component/src/recommendations/Recommendations.tsx](https://github.com/devflowinc/trieve/blob/main/clients/search-component/src/recommendations/Recommendations.tsx). Build artifacts are produced by [clients/search-component/scripts/build.js](https://github.com/devflowinc/trieve/blob/main/clients/search-component/scripts/build.js), which is the file that community issue #3157 identifies as needing a `cjs` output and matching `package.json` CDN-publish commands in addition to the current ESM pipeline. ## Client SDKs and Integrations | Surface | Purpose | Source | |---|---|---| | TypeScript SDK | Typed REST client for web/Node | [clients/ts-sdk/src/sdk.ts](https://github.com/devflowinc/trieve/blob/main/clients/ts-sdk/src/sdk.ts) | | Python SDK | Generated OpenAPI client | [clients/python-sdk/trieve_py_client/api_client.py](https://github.com/devflowinc/trieve/blob/main/clients/python-sdk/trieve_py_client/api_client.py) | | MCP server | Model Context Protocol tool surface | [clients/mcp-server/package.json](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json) | | n8n node | Low-code workflow automation | [clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md) | | Docusaurus theme | `` plugin for docs sites | [clients/docusaurus-theme-search/README.md](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/README.md) | The TypeScript SDK is published as `trieve-ts-sdk` and is consumed directly by the marketing site at version `^0.0.115` ([website/package.json](https://github.com/devflowinc/trieve/blob/main/website/package.json)). The MCP server declares the `model-context-protocol` keyword alongside `trieve`, `mcp`, `ai`, and `search` ([clients/mcp-server/package.json](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json)). The n8n node exposes a `Chunk` resource with `Search` and `Tool Call` operations. `Search` returns matching chunks with relevance scores and highlights, while `Tool Call` accepts a `function_name`, `function_description`, and a list of `parameters` typed as either `boolean` or `number` ([clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md)). Local installation requires symlinking the package into `~/.n8n/custom/` and rebuilding before the node appears in the sidebar. The Docusaurus theme supports `@docusaurus/core` v2 and v3 with React 17, 18, or 19-rc ([clients/docusaurus-theme-search/package.json](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json)). Documented props include `brandLogoImgSrcUrl`, `brandName`, `defaultSearchQueries`, `defaultAiQuestions`, `suggestedQueries`, and `accentColor` (default `#CB53EB`) ([clients/docusaurus-theme-search/README.md](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/README.md)). ## Configuration, Failure Modes, and Community Notes Several recurring community threads map directly onto this layer: - **#3157 (search-component `cjs` build):** Until CommonJS output and matching CDN-publish scripts land in `package.json`, consumers must bundle the ESM artifact themselves. - **#2957 (`create_chunk` dedup):** The server-side handler can drop chunks on duplicate `tracking_id` collisions, so SDK callers and the chat frontend should not assume a 1:1 mapping between request and response. - **#2758 (PDF-to-Markdown demo):** A side-by-side PDF preview and Vision-LLM-generated markdown UI is being built into the chat frontend. - **#2623 (batch delete groups):** A batched delete-groups endpoint is being scoped on the server; once shipped it will propagate into the SDKs and the search-component admin paths. A common failure mode is mismatched peer dependencies — the Docusaurus theme requires React 17/18/19-rc ([clients/docusaurus-theme-search/package.json](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json)), and embedding it in projects pinned to a newer React can break SSR. The n8n node similarly requires symlinking into `~/.n8n/custom/` and rebuilding before the node appears ([clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md)). Operators self-hosting the full stack should also be aware that `trieve-helm-0.2.2` no longer ships database dependencies, with external Glasskube packages now preferred for managed releases. ## See Also - API Reference (https://api.trieve.ai/redoc) - TypeScript SDK (https://ts-sdk.trieve.ai/) - Python SDK (https://pypi.org/project/trieve-py-client/) - Self-hosting guide (https://docs.trieve.ai/self-hosting/docker-compose) - Server and RAG Endpoints - Deployment and Helm Chart --- ## Deployment, Infrastructure, and Sidecar Services ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Backend Server, Handlers, and Workers](#page-2)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/devflowinc/trieve/blob/main/README.md) - [clients/mcp-server/package.json](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json) - [clients/cli/README.md](https://github.com/devflowinc/trieve/blob/main/clients/cli/README.md) - [clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md) - [clients/docusaurus-theme-search/package.json](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json) - [clients/docusaurus-theme-search/example/README.md](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/example/README.md) - [frontends/chat/package.json](https://github.com/devflowinc/trieve/blob/main/frontends/chat/package.json) - [website/README.md](https://github.com/devflowinc/trieve/blob/main/website/README.md) - [website/package.json](https://github.com/devflowinc/trieve/blob/main/website/package.json) - [website/src/pages/rss.xml.js](https://github.com/devflowinc/trieve/blob/main/website/src/pages/rss.xml.js) - [website/src/content/products/trieve-api/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml) - [website/src/content/singles/about-trieve/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/about-trieve/index.yaml)
# Deployment, Infrastructure, and Sidecar Services Trieve ships as a multi-surface platform: a managed REST service, a self-hostable core, a marketing website, a chat frontend, and a family of thin client packages that function as sidecars next to other applications. This page describes how those pieces are organized, how they are deployed, and how the various clients integrate with the core API. ## High-Level Deployment Surfaces The project documents two primary ways to run Trieve: a hosted offering and self-hosting inside the customer's VPC or on-premises hardware. The README explicitly advertises full self-hosting guides for AWS, GCP, generic Kubernetes, and Docker Compose, available through the public documentation page (Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md)). The same README emphasizes that "Sensitive data? Need maximum performance? Host Trieve yourself with terraform templates and no external dependencies" (Source: [website/src/content/singles/homepage/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/homepage/index.yaml)). For Kubernetes users, the community tracks a dedicated Helm chart distribution, `trieve-helm`, whose latest release is **trieve-helm-0.2.2**. The chart is described as "expressing Trieve deployment without any dependencies" (Source: community release notes referenced in issue #2181). Ongoing work (#2181) is migrating the chart from Helm to Glasskube so that databases can be configured externally rather than bundled inside the chart, with tracking issue #2266 already merged to "Refactor helm chart to remove database" (Source: community issue #2181). ```mermaid flowchart LR User[End User] Web[Trieve Website
Astro] Chat[Chat Frontend
Solid.js] SDK[TypeScript SDK
trieve-ts-sdk] Core[(Trieve Core API
REST)] VS[Vector Store
Qdrant] LLM[LLM Providers
OpenRouter / OpenAI / Jina] Helm[trieve-helm-0.2.2
Chart] Self[Self-Hosted
Docker Compose / K8s] Web --> Core Chat --> SDK --> Core Core --> VS Core --> LLM Helm -. deploys .- Core Self -. deploys .- Core User --> Web User --> Chat ``` ## Core Service and Frontend Hosting The two first-party web properties are built independently and consume the same TypeScript SDK. - **Marketing site** lives under `website/` and is built with Astro 5, Tailwind CSS 4, TypeScript, and Keystatic CMS. Content is organized as `src/content/{blogPosts, products, integrations, comparisons, singles}` collections, and the site emits an RSS feed at `src/pages/rss.xml.js` (Source: [website/README.md](https://github.com/devflowinc/trieve/blob/main/website/README.md), [website/src/pages/rss.xml.js](https://github.com/devflowinc/trieve/blob/main/website/src/pages/rss.xml.js)). - **Chat frontend** lives under `frontends/chat/` and is a Solid.js 1.8 application that pulls `trieve-ts-sdk` as a workspace dependency, with `remark-gfm`, `rehype-sanitize`, and `solid-markdown` for rendering model output (Source: [frontends/chat/package.json](https://github.com/devflowinc/trieve/blob/main/frontends/chat/package.json)). - **Marketing site** consumes the SDK at version `^0.0.115` (Source: [website/package.json](https://github.com/devflowinc/trieve/blob/main/website/package.json)), proving the published SDK is the canonical integration point for both Trieve-operated sites and external consumers. The README positions Trieve as "A robust 72-endpoint API productionizing the latest in AI" (Source: [website/src/content/singles/homepage/index.yaml](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/homepage/index.yaml)) backed by integrations with Qdrant for vector storage and OpenRouter/OpenAI/Jina for model inference (Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md)). ## Sidecar and Client Distribution Trieve distributes a constellation of small packages designed to sit alongside another application and forward queries to the core API. Each one in this section is a sidecar in the sense that it has no database of its own and depends on a remote Trieve dataset. | Package | Runtime | Role | Source | | --- | --- | --- | --- | | `trieve-cli` | Node CLI | Configure org/dataset/API key, upload files, poll upload status, ask questions against the knowledge base | [clients/cli/README.md](https://github.com/devflowinc/trieve/blob/main/clients/cli/README.md) | | `mcp-server` | Node (Model Context Protocol) | Exposes Trieve search to MCP-compatible agents; keywords list `trieve`, `mcp`, `ai`, `search`, `model-context-protocol` | [clients/mcp-server/package.json](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json) | | `n8n-nodes-trieve` | n8n node | Adds `tool_call` operations so workflow automations can call into Trieve with structured parameters | [clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md) | | `docusaurus-theme-search` | Docusaurus 2.x / 3.x plugin | Replaces the default docs search bar with Trieve-backed search; dev loop uses `nodemon` + `esbuild` | [clients/docusaurus-theme-search/package.json](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json) | | `search-component` | ESM browser bundle | Drop-in search widget, currently ESM-only — community issue #3157 tracks adding a CommonJS build path | community issue #3157 | The CLI is the most operationally useful sidecar: `trieve configure` collects an Organization ID, Dataset ID, API Key, and User ID, after which `trieve upload` and `trieve ask` interact with the dataset (Source: [clients/cli/README.md](https://github.com/devflowinc/trieve/blob/main/clients/cli/README.md)). The MCP server is positioned as an AI-agent sidecar; its package metadata advertises `model-context-protocol` as the primary keyword (Source: [clients/mcp-server/package.json](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json)). The n8n node demonstrates the same pattern for workflow tooling, including structured tool-call parameters with `parameter_type` of `boolean`, `number`, and so on (Source: [clients/n8n-nodes-trieve/README.md](https://github.com/devflowinc/trieve/blob/main/clients/n8n-nodes-trieve/README.md)). The Docusaurus theme is the clearest example of a Trieve sidecar that swaps an existing subsystem. The package declares peer ranges `@docusaurus/core: ^2 || ^3` and `react: ^17 || ^18 || ^19-rc`, plus a dev stack of `esbuild`, `nodemon`, and `parse5` for hot-reloading the search index pipeline (Source: [clients/docusaurus-theme-search/package.json](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json)). The included `example/` site uses Docusaurus 3.5 and ships with the standard `yarn start`, `yarn build`, and `yarn deploy` commands (Source: [clients/docusaurus-theme-search/example/README.md](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/example/README.md)). ## Infrastructure Configuration Notes A few configuration details are worth flagging for operators: - **Bring-your-own-model surface.** The README documents BYO support for text-embedding, SPLADE, cross-encoder re-ranking, and LLM providers (Source: [README.md](https://github.com/devflowinc/trieve/blob/main/README.md)), which means infrastructure manifests need to declare which external services each deployment reaches. - **Database externalization.** Helm-chart refactoring (issue #2266) deliberately removes the database from the chart so it can be installed as an external Glasskube package, simplifying per-environment overrides (Source: community issue #2181). - **Search-component bundle target.** Until issue #3157 lands, only the ESM build is published to the CDN; consumers needing CommonJS must either migrate their bundler or wait for the build script in `clients/search-component/scrripts/build.js` to emit both targets (Source: community issue #3157). - **SDK version coupling.** The marketing site pins `trieve-ts-sdk` to `^0.0.115` while the chat frontend uses the workspace package `*` (Source: [website/package.json](https://github.com/devflowinc/trieve/blob/main/website/package.json), [frontends/chat/package.json](https://github.com/devflowinc/trieve/blob/main/frontends/chat/package.json)); release pipelines must keep both in step. ## See Also - [Trieve API product page](https://github.com/devflowinc/trieve/blob/main/website/src/content/products/trieve-api/index.yaml) - [Trieve About / Mission](https://github.com/devflowinc/trieve/blob/main/website/src/content/singles/about-trieve/index.yaml) - [CLI README](https://github.com/devflowinc/trieve/blob/main/clients/cli/README.md) - [MCP server package](https://github.com/devflowinc/trieve/blob/main/clients/mcp-server/package.json) - [Docusaurus theme search package](https://github.com/devflowinc/trieve/blob/main/clients/docusaurus-theme-search/package.json) --- --- ## Pitfall Log Project: devflowinc/trieve Summary: Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification. ## 1. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/devflowinc/trieve ## 2. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/devflowinc/trieve/issues/4017 ## 3. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/devflowinc/trieve ## 4. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/devflowinc/trieve ## 5. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/devflowinc/trieve ## 6. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/devflowinc/trieve/issues/3975 ## 7. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/devflowinc/trieve ## 8. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/devflowinc/trieve