# truefoundry/cognita architecture

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

- Interactive diagram: https://gitdiagram.com/truefoundry/cognita
- Repository: https://github.com/truefoundry/cognita

## Overview

##### Main Components
- Backend API Server: Located in the “backend/server” directory. This FastAPI server handles API routing, query controllers, and request/response processing.
- Data Indexer/Job: Shown in the “backend/indexer” directory. This is the asynchronous job that scans data sources, chunking and embedding documents.
- Metadata Store: Found under “backend/modules/metadata_store”. This module (powered by Prisma and Postgres) captures collection metadata, data source configuration, and links between documents and vector DB entries.
- Model Gateway: Under “backend/modules/model_gateway”. It is the central proxy to manage embedding models and LLM requests.
- Vector Database: Under “backend/modules/vector_db”. Components here link to external scalable vector stores such as Qdrant, SingleStore, etc. Indicate external services with a shared container-like symbol.
- Data Loaders & Parsers: Within “backend/modules/dataloaders” and “backend/modules/parsers” respectively, which ingest and split file data (from various sources like S3, local directories, web, etc.).
- Query Controllers: Located under “backend/modules/query_controllers”. They encapsulate the logic that bridges the user queries from the API server with downstream retrieval and answer generation.
- Deployment and Orchestration: The presence of Dockerfiles in both frontend and backend, along with deployment scripts (docker-compose.yaml and the “deployment” directory), implies containerized builds and orchestration.

##### Relationships and Data Flow
- Data flows from “data sources” (external systems, S3, local files, etc.) into the Data Loader, which then hands off raw data to the Parser. Parsed chunks then pass through an Embedding step (leveraging the Model Gateway) and are finally ingested and stored in the Vector DB.
- The Metadata Store keeps track of collections, configurations, and ingestion state.
- The API Server (with its query controllers) handles incoming QnA requests. It takes the user query, uses the Model Gateway to generate embeddings, retrieves relevant document chunks from the Vector DB, and then (optionally) leverages rerankers or additional LLM calls to refine answers.
- The Frontend communicates with the Backend API Server (using REST endpoints defined in “backend/server/routers”) to drive the UI-based interactions.

##### Architectural Patterns & Design Principles
- Modular / Microservice-based Approach: Each RAG component (indexing, query handling, UI, vector database, etc.) is organized in its own module or service. They are clearly separated for scalability.
- API-Driven Communication: The system cleanly separates responsibilities with API calls (see the “query_controller” decorators and FastAPI endpoints).
- Containerization and Orchestration: Docker and docker-compose are used to encapsulate services ensuring environment consistency in local and production.
- Extensibility: The instructions in the README for customizing dataloaders, parsers, vector databases, and query controllers reveal a plug-and-play design pattern.

##### Being Detailed Yet Organized
- The bottom layer represents external integrations and persistent stores (Data Sources, Vector DB, Metadata Store).
- The middle layer covers the processing pipelines (Indexing Job, Embedding, Parsing, etc.).
- The top layer represents the API and Query handling (Backend API Server, Query Controllers) along with the Frontend.
- Optionally, an inset could show the CI/CD / deployment portion with Docker, docker-compose, and TrueFoundry integration for reference.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction Layer"
        UI["Frontend UI (React/TS)"]:::frontend
        APIServer["Backend API Server (FastAPI)"]:::backend
        UI -->|"REST"| APIServer
    end

    %% Query Processing Layer
    subgraph "Query Processing Layer"
        QueryControllers["Query Controllers"]:::backend
        ModelGateway["Model Gateway (LLM/Embedding Gateway)"]:::backend
        APIServer -->|"query"| QueryControllers
        QueryControllers -->|"embedding/retrieval"| ModelGateway
        ModelGateway -->|"fetch documents"| VectorDB
    end

    %% Data Ingestion Pipeline
    subgraph "Data Ingestion Pipeline"
        DataSources["Data Sources (External)"]:::external
        DataLoaders["Data Loaders"]:::data
        Parsers["Parsers"]:::data
        DataIndexer["Data Indexer/Job"]:::data
        MetadataStore["Metadata Store (Prisma+Postgres)"]:::data
        VectorDB["Vector Database (External)"]:::data

        DataSources -->|"raw data"| DataLoaders
        DataLoaders -->|"ingest"| Parsers
        Parsers -->|"parse"| DataIndexer
        DataIndexer -->|"store metadata"| MetadataStore
        DataIndexer -->|"embedding"| ModelGateway
        DataIndexer -->|"ingest"| VectorDB
    end

    %% Deployment & Orchestration
    Deployment["Deployment & Orchestration"]:::deployment
    Deployment --- UI
    Deployment --- APIServer
    Deployment --- DataIndexer
    Deployment --- MetadataStore
    Deployment --- ModelGateway
    Deployment --- VectorDB
    Deployment --- DataLoaders
    Deployment --- Parsers
    Deployment --- QueryControllers

    %% Click Events
    click UI "https://github.com/truefoundry/cognita/tree/main/frontend"
    click APIServer "https://github.com/truefoundry/cognita/tree/main/backend/server"
    click DataIndexer "https://github.com/truefoundry/cognita/tree/main/backend/indexer"
    click MetadataStore "https://github.com/truefoundry/cognita/tree/main/backend/modules/metadata_store"
    click ModelGateway "https://github.com/truefoundry/cognita/tree/main/backend/modules/model_gateway"
    click VectorDB "https://github.com/truefoundry/cognita/tree/main/backend/modules/vector_db"
    click DataLoaders "https://github.com/truefoundry/cognita/tree/main/backend/modules/dataloaders"
    click Parsers "https://github.com/truefoundry/cognita/tree/main/backend/modules/parsers"
    click QueryControllers "https://github.com/truefoundry/cognita/tree/main/backend/modules/query_controllers"
    click Deployment "https://github.com/truefoundry/cognita/tree/main/deployment"

    %% Styles
    classDef frontend fill:#E8F5FF,stroke:#2C82C9,stroke-width:2px;
    classDef backend fill:#FFEFD5,stroke:#D2691E,stroke-width:2px;
    classDef data fill:#E0FFE0,stroke:#008000,stroke-width:2px;
    classDef deployment fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
    classDef external fill:#FFCCCC,stroke:#CC0000,stroke-width:2px;
```
