How truefoundry/cognita works
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.