# d3byn/cortex architecture

> Architecture diagram of the GitHub repository d3byn/cortex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/d3byn/cortex
- Repository: https://github.com/d3byn/cortex

## Overview

Cortex is a document-ingestion and grounded question-answering platform. Users upload PDF, TXT, or Markdown files for background parsing, chunking, embedding, and indexing; they can then search or ask questions and receive cited answers with a groundedness check. The graph preserves the separate API, ingestion, retrieval, and answer-generation stages. Several subsystem links rely on the README or SOURCE INDEX references; the frontend-to-API connection is documented only at a high level.

Main entry points: [`backend/app/retrieval/hybrid.py`](https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/hybrid.py) (Hybrid Retrieval), [`backend/app/ingestion/background.py`](https://github.com/d3byn/cortex/blob/main/backend/app/ingestion/background.py) (Background Ingestion), [`backend/app/main.py`](https://github.com/d3byn/cortex/blob/main/backend/app/main.py) (FastAPI Application), [`backend/app/api/documents.py`](https://github.com/d3byn/cortex/blob/main/backend/app/api/documents.py) (Document Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface & API"]
  node_frontend["Chat Frontend<br/>[app.py]"]
  node_api["FastAPI Application<br/>[main.py]"]
  node_ingest_api["Ingest Endpoint<br/>[ingest.py]"]
  node_search_api["Search Endpoint<br/>[search.py]"]
  node_query_api["Query Endpoint<br/>[query.py]"]
  node_documents_api["Document Management<br/>[documents.py]"]
  node_schemas["API Schemas<br/>[models.py]"]
end

subgraph group_ingestion["Document Ingestion"]
  node_background["Background Ingestion<br/>[background.py]"]
  node_parsers["File Parsing<br/>[parsers.py]"]
  node_chunker["Text Chunking<br/>[chunker.py]"]
end

subgraph group_retrieval["Search &amp; Retrieval"]
  node_embeddings["Embedding Service<br/>[embeddings.py]"]
  node_hybrid["Hybrid Retrieval<br/>[hybrid.py]"]
  node_fusion["Rank Fusion<br/>[fusion.py]"]
  node_lookup["Chunk Lookup<br/>[lookup.py]"]
  node_reranker["Cross-Encoder Reranker<br/>[reranker.py]"]
end

subgraph group_answering["Answer Generation"]
  node_pipeline["LangGraph Pipeline<br/>[pipeline.py]"]
  node_graph_nodes["Query &amp; Grounding Steps<br/>[nodes.py]"]
  node_gemini{{"Gemini API"}}
  node_tracer["Query Tracing<br/>[tracer.py]"]
end

subgraph group_storage["Persistence &amp; State"]
  node_vector[("FAISS Index<br/>[vector_store.py]")]
  node_keyword[("BM25 Index<br/>[keyword_store.py]")]
  node_database[("SQLite Records<br/>[models.py]")]
  node_query_cache[("Response Cache<br/>[response_cache.py]")]
end

node_user(("User"))

node_user -->|"asks questions"| node_frontend
node_frontend -.->|"uses API"| node_api
node_api -->|"registers route"| node_ingest_api
node_api -->|"registers route"| node_search_api
node_api -->|"registers route"| node_query_api
node_api -->|"registers route"| node_documents_api
node_ingest_api -->|"schedules processing"| node_background
node_ingest_api -->|"detects file type"| node_parsers
node_ingest_api -->|"creates job"| node_database
node_background -->|"parses file"| node_parsers
node_background -->|"chunks text"| node_chunker
node_background -->|"embeds chunks"| node_embeddings
node_background -->|"saves records"| node_database
node_background -->|"indexes vectors"| node_vector
node_background -->|"updates index"| node_keyword
node_background -->|"invalidates cache"| node_query_cache
node_search_api -->|"retrieves results"| node_hybrid
node_hybrid -->|"embeds query"| node_embeddings
node_hybrid -->|"searches vectors"| node_vector
node_hybrid -->|"searches terms"| node_keyword
node_hybrid -->|"fuses rankings"| node_fusion
node_hybrid -->|"loads chunks"| node_lookup
node_hybrid -->|"reranks results"| node_reranker
node_hybrid -->|"filters documents"| node_database
node_query_api -->|"checks and saves"| node_query_cache
node_query_api -->|"invokes pipeline"| node_pipeline
node_query_api -->|"creates trace"| node_tracer
node_pipeline -->|"orchestrates steps"| node_graph_nodes
node_graph_nodes -->|"retrieves context"| node_hybrid
node_graph_nodes -->|"generates and audits"| node_gemini
node_graph_nodes -->|"reads records"| node_database
node_documents_api -->|"manages records"| node_database
node_documents_api -->|"removes vectors"| node_vector
node_documents_api -->|"updates index"| node_keyword
node_documents_api -->|"invalidates cache"| node_query_cache

click node_frontend "https://github.com/d3byn/cortex/blob/main/frontend/app.py"
click node_api "https://github.com/d3byn/cortex/blob/main/backend/app/main.py"
click node_ingest_api "https://github.com/d3byn/cortex/blob/main/backend/app/api/ingest.py"
click node_search_api "https://github.com/d3byn/cortex/blob/main/backend/app/api/search.py"
click node_query_api "https://github.com/d3byn/cortex/blob/main/backend/app/api/query.py"
click node_documents_api "https://github.com/d3byn/cortex/blob/main/backend/app/api/documents.py"
click node_schemas "https://github.com/d3byn/cortex/blob/main/backend/app/schemas/models.py"
click node_background "https://github.com/d3byn/cortex/blob/main/backend/app/ingestion/background.py"
click node_parsers "https://github.com/d3byn/cortex/blob/main/backend/app/ingestion/parsers.py"
click node_chunker "https://github.com/d3byn/cortex/blob/main/backend/app/ingestion/chunker.py"
click node_embeddings "https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/embeddings.py"
click node_hybrid "https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/hybrid.py"
click node_fusion "https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/fusion.py"
click node_lookup "https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/lookup.py"
click node_reranker "https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/reranker.py"
click node_vector "https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/vector_store.py"
click node_keyword "https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/keyword_store.py"
click node_database "https://github.com/d3byn/cortex/blob/main/backend/app/db/models.py"
click node_query_cache "https://github.com/d3byn/cortex/blob/main/backend/app/cache/response_cache.py"
click node_pipeline "https://github.com/d3byn/cortex/blob/main/backend/app/graph/pipeline.py"
click node_graph_nodes "https://github.com/d3byn/cortex/blob/main/backend/app/graph/nodes.py"
click node_tracer "https://github.com/d3byn/cortex/blob/main/backend/app/tracing/tracer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_api,node_ingest_api,node_search_api,node_query_api,node_documents_api,node_schemas,node_user toneBlue
class node_background,node_parsers,node_chunker toneAmber
class node_embeddings,node_hybrid,node_fusion,node_lookup,node_reranker toneMint
class node_pipeline,node_graph_nodes,node_gemini,node_tracer toneRose
class node_vector,node_keyword,node_database,node_query_cache toneIndigo
```

## Components

### User Interface & API

- [Chat Frontend](https://github.com/d3byn/cortex/blob/main/frontend/app.py): `frontend/app.py`
- [FastAPI Application](https://github.com/d3byn/cortex/blob/main/backend/app/main.py): `backend/app/main.py`
- [Ingest Endpoint](https://github.com/d3byn/cortex/blob/main/backend/app/api/ingest.py): `backend/app/api/ingest.py`
- [Search Endpoint](https://github.com/d3byn/cortex/blob/main/backend/app/api/search.py): `backend/app/api/search.py`
- [Query Endpoint](https://github.com/d3byn/cortex/blob/main/backend/app/api/query.py): `backend/app/api/query.py`
- [Document Management](https://github.com/d3byn/cortex/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`
- [API Schemas](https://github.com/d3byn/cortex/blob/main/backend/app/schemas/models.py): `backend/app/schemas/models.py`

### Document Ingestion

- [Background Ingestion](https://github.com/d3byn/cortex/blob/main/backend/app/ingestion/background.py): `backend/app/ingestion/background.py`
- [File Parsing](https://github.com/d3byn/cortex/blob/main/backend/app/ingestion/parsers.py): `backend/app/ingestion/parsers.py`
- [Text Chunking](https://github.com/d3byn/cortex/blob/main/backend/app/ingestion/chunker.py): `backend/app/ingestion/chunker.py`

### Search & Retrieval

- [Embedding Service](https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/embeddings.py): `backend/app/retrieval/embeddings.py`
- [Hybrid Retrieval](https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/hybrid.py): `backend/app/retrieval/hybrid.py`
- [Rank Fusion](https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/fusion.py): `backend/app/retrieval/fusion.py`
- [Chunk Lookup](https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/lookup.py): `backend/app/retrieval/lookup.py`
- [Cross-Encoder Reranker](https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/reranker.py): `backend/app/retrieval/reranker.py`

### Answer Generation

- [LangGraph Pipeline](https://github.com/d3byn/cortex/blob/main/backend/app/graph/pipeline.py): `backend/app/graph/pipeline.py`
- [Query & Grounding Steps](https://github.com/d3byn/cortex/blob/main/backend/app/graph/nodes.py): `backend/app/graph/nodes.py`
- **Gemini API**
- [Query Tracing](https://github.com/d3byn/cortex/blob/main/backend/app/tracing/tracer.py): `backend/app/tracing/tracer.py`

### Persistence & State

- [FAISS Index](https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/vector_store.py): `backend/app/retrieval/vector_store.py`
- [BM25 Index](https://github.com/d3byn/cortex/blob/main/backend/app/retrieval/keyword_store.py): `backend/app/retrieval/keyword_store.py`
- [SQLite Records](https://github.com/d3byn/cortex/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Response Cache](https://github.com/d3byn/cortex/blob/main/backend/app/cache/response_cache.py): `backend/app/cache/response_cache.py`

### Other components

- **User**

## Connections

- User → Chat Frontend: asks questions (evidence: `README.md`)
- Chat Frontend → FastAPI Application: uses API
- FastAPI Application → Ingest Endpoint: registers route (evidence: `backend/app/main.py`)
- FastAPI Application → Search Endpoint: registers route (evidence: `backend/app/main.py`)
- FastAPI Application → Query Endpoint: registers route (evidence: `backend/app/main.py`)
- FastAPI Application → Document Management: registers route (evidence: `backend/app/main.py`)
- Ingest Endpoint → Background Ingestion: schedules processing (evidence: `backend/app/api/ingest.py`)
- Ingest Endpoint → File Parsing: detects file type (evidence: `backend/app/api/ingest.py`)
- Ingest Endpoint → SQLite Records: creates job (evidence: `backend/app/api/ingest.py`)
- Background Ingestion → File Parsing: parses file (evidence: `backend/app/ingestion/background.py`)
- Background Ingestion → Text Chunking: chunks text (evidence: `backend/app/ingestion/background.py`)
- Background Ingestion → Embedding Service: embeds chunks (evidence: `backend/app/ingestion/background.py`)
- Background Ingestion → SQLite Records: saves records (evidence: `backend/app/ingestion/background.py`)
- Background Ingestion → FAISS Index: indexes vectors (evidence: `backend/app/ingestion/background.py`)
- Background Ingestion → BM25 Index: updates index (evidence: `backend/app/ingestion/background.py`)
- Background Ingestion → Response Cache: invalidates cache (evidence: `backend/app/ingestion/background.py`)
- Search Endpoint → Hybrid Retrieval: retrieves results (evidence: `backend/app/api/search.py`)
- Hybrid Retrieval → Embedding Service: embeds query (evidence: `backend/app/retrieval/hybrid.py`)
- Hybrid Retrieval → FAISS Index: searches vectors (evidence: `backend/app/retrieval/hybrid.py`)
- Hybrid Retrieval → BM25 Index: searches terms (evidence: `backend/app/retrieval/hybrid.py`)
- Hybrid Retrieval → Rank Fusion: fuses rankings (evidence: `backend/app/retrieval/hybrid.py`)
- Hybrid Retrieval → Chunk Lookup: loads chunks (evidence: `backend/app/retrieval/hybrid.py`)
- Hybrid Retrieval → Cross-Encoder Reranker: reranks results (evidence: `backend/app/retrieval/hybrid.py`)
- Hybrid Retrieval → SQLite Records: filters documents (evidence: `backend/app/retrieval/hybrid.py`)
- Query Endpoint → Response Cache: checks and saves (evidence: `backend/app/api/query.py`)
- Query Endpoint → LangGraph Pipeline: invokes pipeline (evidence: `backend/app/api/query.py`)
- Query Endpoint → Query Tracing: creates trace (evidence: `backend/app/api/query.py`)
- LangGraph Pipeline → Query & Grounding Steps: orchestrates steps (evidence: `backend/app/graph/pipeline.py`)
- Query & Grounding Steps → Hybrid Retrieval: retrieves context (evidence: `backend/app/graph/nodes.py`)
- Query & Grounding Steps → Gemini API: generates and audits (evidence: `backend/app/graph/nodes.py`)
- Query & Grounding Steps → SQLite Records: reads records (evidence: `backend/app/graph/nodes.py`)
- Document Management → SQLite Records: manages records (evidence: `backend/app/api/documents.py`)
- Document Management → FAISS Index: removes vectors (evidence: `backend/app/api/documents.py`)
- Document Management → BM25 Index: updates index (evidence: `backend/app/api/documents.py`)
- Document Management → Response Cache: invalidates cache (evidence: `backend/app/api/documents.py`)