# devflowinc/trieve architecture

> Architecture diagram of the GitHub repository devflowinc/trieve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devflowinc/trieve
- Repository: https://github.com/devflowinc/trieve

## Overview

##### Main components
- Frontend Clients: There are several user interfaces (e.g., the “chat”, “dashboard”, “search” apps under the frontends folder, along with shared UI utilities). These components are implemented mostly in JavaScript/Typescript (React, Vite, Tailwind, etc.).
- Backend API Server: The “server” directory (Rust-based) is the core API service. It handles routes such as authentication, data ingestion, analytics, search, messaging, file handling, and more.
- Worker Services: Several binaries exist inside the server (and the “batch-etl” folder) such as ingestion-worker, file-worker, delete-worker, crawl-worker, reindex-worker, etc. These execute asynchronous and background tasks and are deployed in separate Docker containers.
- Data Storage & Databases: There are migration files and configuration for Postgres (and Diesel migrations), ClickHouse (for analytics and fast querying), and other databases. The presence of Qdrant in charts and integration instructions signals a dedicated vector database used in the dense vector (embedding) search flow.
- External Integrations: The system integrates with external services such as OpenAI (LLM API keys), embedding providers, Stripe (for subscription management), and Keycloak for authentication, as well as using third-party embeddings and reranking models.
- Additional Services: The project includes specialized components like “pdf2md” (a service for PDF-to-markdown conversion) and “hallucination-detection” (another Rust project for quality control). There are also multiple client SDKs (python, typescript) and search components.
- Infrastructure & Deployment: The presence of Dockerfiles, docker-compose configurations, Helm charts (in the “charts” directory), Terraform scripts, and various CI/CD configurations (under .github/workflows) indicate that the deployment architecture is containerized and orchestrated (potentially via Kubernetes or docker-compose).

##### Relationships and data flows
- Users interact with the Frontend UI and dashboards, which in turn make API calls (e.g., via REST) to the Backend API Server.
- The API server handles incoming requests, interacts with databases (Postgres for transactional data, ClickHouse for analytics, Qdrant for vector search), and communicates with worker services by enqueuing tasks (or through service calls).
- Worker processes (ingestion, file, crawl, delete, etc.) perform background jobs and update the databases.
- For search and recommendation queries, the server may first retrieve candidate chunks from full-text or vector search (leveraging systems like Qdrant or Redis caches) and then trigger cross-encoder re-ranking.
- External services (LLM APIs, embedding model services, Stripe for payments) are called either synchronously (on-demand via API routes) or asynchronously via worker processes.
- The infrastructure is deployed using container orchestration and Helm charts (with separate configurations for cloud providers like AWS, GCP, and on-prem solutions) as indicated by the “charts” and “terraform” directories.

##### Architectural patterns and design principles
- Microservices Architecture: Although all the code lives in one monorepo, there is a clear separation between the API server, various worker processes, and the client frontends. Each service has its own Dockerfile and deployment configuration.
- Layered Structure: The system is organized into presentation (frontends), business logic/API (server), background processing (workers), and data storage layers.
- Extensibility & Plug-In Points: The configuration for user-provided models (for embeddings, re-ranking, etc.), the integration with third-party services (like OpenAI, Stripe, Keycloak), and SDK clients for multiple languages show a focus on modularity and extensibility.
- Infrastructure-as-Code: The presence of various Helm charts, Terraform configuration files, and Docker Compose manifests emphasizes reproducible and self-contained deployments.
- Self-hosting Design: Clear instructions in the README and multiple “.env” files for different services illustrate that self-hosting and deployment in a VPC or on-premise environment is central to the project’s design.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "User Interaction"
        Chat["Chat Frontend"]:::client
        Dashboard["Dashboard Frontend"]:::client
        Search["Search Frontend"]:::client
    end

    subgraph "API & Business Logic"
        API["Trieve API Server (Rust)"]:::api
    end

    subgraph "Worker Services"
        Ingestion["Ingestion Worker"]:::worker
        FileWorker["File Worker"]:::worker
        DeleteWorker["Delete Worker"]:::worker
        CrawlWorker["Crawl Worker"]:::worker
        ReindexWorker["Reindex Worker"]:::worker
    end

    subgraph "Data Storage"
        Postgres["Postgres Database (Diesel Migrations)"]:::db
        ClickHouse["ClickHouse Analytics DB"]:::db
        Qdrant["Qdrant Vector Store"]:::db
    end

    subgraph "External Integrations"
        OpenAI["OpenAI/LLM Providers"]:::external
        Stripe["Stripe API"]:::external
        Keycloak["Keycloak Auth"]:::external
    end

    subgraph "Additional Services"
        PDF2MD["PDF-to-Markdown Service"]:::service
        Hallucination["Hallucination Detection Service"]:::service
    end

    subgraph "Client Libraries & SDKs"
        PythonSDK["Python SDK"]:::sdk
        TSSDK["TypeScript SDK"]:::sdk
    end

    subgraph "Infrastructure & Deployment"
        Docker["Docker Compose & Dockerfiles"]:::infra
        Terraform["Terraform Scripts"]:::infra
        CI["GitHub Actions CI/CD"]:::infra
    end

    %% Connections between User Interaction and API
    Chat -->|"REST"| API
    Dashboard -->|"REST"| API
    Search -->|"REST"| API

    %% API triggers Worker Services
    API -->|"enqueue"| Ingestion
    API -->|"enqueue"| FileWorker
    API -->|"enqueue"| DeleteWorker
    API -->|"enqueue"| CrawlWorker
    API -->|"enqueue"| ReindexWorker

    %% API interacts with Data Storage
    API -->|"queries"| Postgres
    API -->|"queries"| ClickHouse
    API -->|"vector_search"| Qdrant

    %% Worker Services update Data Storage
    Ingestion -->|"updates"| Postgres
    Ingestion -->|"updates"| ClickHouse
    FileWorker -->|"updates"| Postgres
    DeleteWorker -->|"updates"| Postgres
    CrawlWorker -->|"updates"| Postgres
    ReindexWorker -->|"updates"| Qdrant

    %% API communicates with External Integrations
    API -->|"calls"| OpenAI
    API -->|"calls"| Stripe
    API -->|"calls"| Keycloak

    %% API uses Additional Services
    API -->|"processes"| PDF2MD
    API -->|"processes"| Hallucination

    %% CI/CD deploys services
    CI -->|"deploys"| API
    CI -->|"deploys"| Ingestion
    CI -->|"deploys"| FileWorker
    CI -->|"deploys"| DeleteWorker
    CI -->|"deploys"| CrawlWorker
    CI -->|"deploys"| ReindexWorker
    CI -->|"deploys"| Chat
    CI -->|"deploys"| Dashboard
    CI -->|"deploys"| Search

    %% Infrastructure provisions Data Storage
    Terraform -->|"provisions"| Postgres
    Terraform -->|"provisions"| ClickHouse
    Terraform -->|"provisions"| Qdrant

    %% Docker containerizes components
    Docker -->|"containers"| API
    Docker -->|"containers"| Ingestion
    Docker -->|"containers"| FileWorker
    Docker -->|"containers"| DeleteWorker
    Docker -->|"containers"| CrawlWorker
    Docker -->|"containers"| ReindexWorker
    Docker -->|"containers"| Chat
    Docker -->|"containers"| Dashboard
    Docker -->|"containers"| Search

    %% Click Events
    click Chat "https://github.com/devflowinc/trieve/tree/main/frontends/chat"
    click Dashboard "https://github.com/devflowinc/trieve/tree/main/frontends/dashboard"
    click Search "https://github.com/devflowinc/trieve/tree/main/frontends/search"
    click API "https://github.com/devflowinc/trieve/tree/main/server"
    click Ingestion "https://github.com/devflowinc/trieve/blob/main/server/bin/ingestion-worker.rs"
    click FileWorker "https://github.com/devflowinc/trieve/blob/main/server/bin/file-worker.rs"
    click DeleteWorker "https://github.com/devflowinc/trieve/blob/main/server/bin/delete-worker.rs"
    click CrawlWorker "https://github.com/devflowinc/trieve/blob/main/server/bin/crawl-worker.rs"
    click ReindexWorker "https://github.com/devflowinc/trieve/blob/main/server/bin/reindex-worker.rs"
    click Postgres "https://github.com/devflowinc/trieve/tree/main/server/migrations"
    click ClickHouse "https://github.com/devflowinc/trieve/tree/main/server/ch_migrations"
    click PDF2MD "https://github.com/devflowinc/trieve/tree/main/pdf2md"
    click Hallucination "https://github.com/devflowinc/trieve/tree/main/hallucination-detection"
    click PythonSDK "https://github.com/devflowinc/trieve/tree/main/clients/python-sdk"
    click TSSDK "https://github.com/devflowinc/trieve/tree/main/clients/ts-sdk"
    click Docker "https://github.com/devflowinc/trieve/blob/main/docker-compose.yml"
    click Terraform "https://github.com/devflowinc/trieve/tree/main/terraform"
    click CI "https://github.com/devflowinc/trieve/tree/main/.github/workflows"

    %% Styles
    classDef client fill:#D8BFD8,stroke:#4B0082,stroke-width:2px;
    classDef api fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef worker fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef db fill:#D3D3D3,stroke:#696969,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#FFA500,stroke-width:2px;
    classDef service fill:#40E0D0,stroke:#008080,stroke-width:2px;
    classDef sdk fill:#9370DB,stroke:#6A5ACD,stroke-width:2px;
    classDef infra fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
```
