# saksham6/document-rag-prototype architecture

> Architecture diagram of the GitHub repository saksham6/document-rag-prototype, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saksham6/document-rag-prototype
- Repository: https://github.com/saksham6/document-rag-prototype

## Overview

Document RAG Prototype is a database-backed service for organizing knowledge bases, uploading and processing PDF/TXT files, and answering questions with retrieved document sources. The principal workflow runs through FastAPI routes: upload and persist metadata, explicitly ingest into chunks, embed chunks, then search via query embedding and pgvector before generating a grounded answer. README documents a browser UI and health endpoints as additional capabilities. Edges follow the sampled route/service calls and README; unsampled route wiring to schemas and persistence is not expanded beyond documented behavior.

Main entry points: [`app/api/main.py`](https://github.com/saksham6/document-rag-prototype/blob/main/app/api/main.py) (FastAPI app), [`src/document_rag_prototype/api/routes/ingestion.py`](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/ingestion.py) (Ingestion endpoints), [`src/document_rag_prototype/db/session.py`](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/db/session.py) (Database sessions), [`src/document_rag_prototype/api/routes/rag.py`](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/rag.py) (Search endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and UI"]
  node_browser["Browser UI<br/>[index.html]"]
  node_app["FastAPI app<br/>[main.py]"]
  node_knowledge_routes["Knowledge bases<br/>[knowledge_bases.py]"]
  node_document_routes["Document and chunk routes<br/>[documents.py]"]
  node_health["Health checks<br/>[health.py]"]
  node_schemas["API schemas<br/>[models.py]"]
end

subgraph group_processing["Document processing"]
  node_ingestion_routes["Ingestion endpoints<br/>[ingestion.py]"]
  node_config["Runtime config<br/>[config.py]"]
  node_ingestion_service["Extract and chunk"]
end

subgraph group_rag["Retrieval and answers"]
  node_rag_route["Search endpoint<br/>[rag.py]"]
  node_embedding_service["Embedding service"]
  node_retrieval_service["Vector retrieval"]
  node_generation_service["Answer generation"]
end

subgraph group_persistence["Persistence"]
  node_models["ORM models<br/>[models.py]"]
  node_session["Database sessions<br/>[session.py]"]
  node_postgres[("PostgreSQL / pgvector")]
end

node_user(("User"))
node_openai{{"OpenAI API"}}

node_user -->|"uses"| node_browser
node_browser -.->|"accesses"| node_app
node_app -->|"registers"| node_knowledge_routes
node_app -->|"registers"| node_document_routes
node_app -->|"registers"| node_ingestion_routes
node_app -->|"registers"| node_rag_route
node_app -->|"registers"| node_health
node_knowledge_routes -.->|"gets sessions"| node_session
node_document_routes -->|"gets sessions"| node_session
node_document_routes -->|"reads and writes"| node_models
node_ingestion_routes -->|"gets sessions"| node_session
node_ingestion_routes -->|"reads and writes"| node_models
node_ingestion_routes -->|"gets upload path"| node_config
node_ingestion_routes -->|"extracts and chunks"| node_ingestion_service
node_ingestion_routes -->|"embeds chunks"| node_embedding_service
node_rag_route -->|"gets session"| node_session
node_rag_route -->|"requests matches"| node_retrieval_service
node_rag_route -->|"requests answer"| node_generation_service
node_retrieval_service -->|"embeds query"| node_embedding_service
node_retrieval_service -->|"queries vectors"| node_postgres
node_generation_service -->|"generates answer"| node_openai
node_embedding_service -->|"creates embeddings"| node_openai
node_session -->|"connects"| node_postgres
node_health -->|"checks database"| node_session
node_schemas -.->|"validates requests"| node_rag_route

click node_browser "https://github.com/saksham6/document-rag-prototype/blob/main/static/index.html"
click node_app "https://github.com/saksham6/document-rag-prototype/blob/main/app/api/main.py"
click node_knowledge_routes "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/knowledge_bases.py"
click node_document_routes "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/documents.py"
click node_ingestion_routes "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/ingestion.py"
click node_rag_route "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/rag.py"
click node_health "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/health.py"
click node_schemas "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/schemas/models.py"
click node_config "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/core/config.py"
click node_ingestion_service "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/services/ingestion_service.py"
click node_embedding_service "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/services/embedding_service.py"
click node_retrieval_service "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/services/retrieval_service.py"
click node_generation_service "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/services/generation_service.py"
click node_models "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/db/models.py"
click node_session "https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/db/session.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_browser,node_app,node_knowledge_routes,node_document_routes,node_health,node_schemas,node_user toneBlue
class node_ingestion_routes,node_config,node_ingestion_service toneAmber
class node_rag_route,node_embedding_service,node_retrieval_service,node_generation_service,node_openai toneMint
class node_models,node_session,node_postgres toneRose
```

## Components

### API and UI

- [Browser UI](https://github.com/saksham6/document-rag-prototype/blob/main/static/index.html): `static/index.html`
- [FastAPI app](https://github.com/saksham6/document-rag-prototype/blob/main/app/api/main.py): `app/api/main.py`
- [Knowledge bases](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/knowledge_bases.py): `src/document_rag_prototype/api/routes/knowledge_bases.py`
- [Document and chunk routes](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/documents.py): `src/document_rag_prototype/api/routes/documents.py`
- [Health checks](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/health.py): `src/document_rag_prototype/api/routes/health.py`
- [API schemas](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/schemas/models.py): `src/document_rag_prototype/api/schemas/models.py`

### Document processing

- [Ingestion endpoints](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/ingestion.py): `src/document_rag_prototype/api/routes/ingestion.py`
- [Runtime config](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/core/config.py): `src/document_rag_prototype/core/config.py`
- [Extract and chunk](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/services/ingestion_service.py): `src/document_rag_prototype/services/ingestion_service.py`

### Retrieval and answers

- [Search endpoint](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/api/routes/rag.py): `src/document_rag_prototype/api/routes/rag.py`
- [Embedding service](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/services/embedding_service.py): `src/document_rag_prototype/services/embedding_service.py`
- [Vector retrieval](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/services/retrieval_service.py): `src/document_rag_prototype/services/retrieval_service.py`
- [Answer generation](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/services/generation_service.py): `src/document_rag_prototype/services/generation_service.py`

### Persistence

- [ORM models](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/db/models.py): `src/document_rag_prototype/db/models.py`
- [Database sessions](https://github.com/saksham6/document-rag-prototype/blob/main/src/document_rag_prototype/db/session.py): `src/document_rag_prototype/db/session.py`
- **PostgreSQL / pgvector**

### Other components

- **User**
- **OpenAI API**

## Connections

- User → Browser UI: uses (evidence: `README.md`)
- Browser UI → FastAPI app: accesses (evidence: `README.md`)
- FastAPI app → Knowledge bases: registers (evidence: `app/api/main.py`)
- FastAPI app → Document and chunk routes: registers (evidence: `app/api/main.py`)
- FastAPI app → Ingestion endpoints: registers (evidence: `app/api/main.py`)
- FastAPI app → Search endpoint: registers (evidence: `app/api/main.py`)
- FastAPI app → Health checks: registers (evidence: `app/api/main.py`)
- Knowledge bases → Database sessions: gets sessions (evidence: `src/document_rag_prototype/api/routes/knowledge_bases.py`)
- Document and chunk routes → Database sessions: gets sessions (evidence: `src/document_rag_prototype/api/routes/documents.py`)
- Document and chunk routes → ORM models: reads and writes (evidence: `src/document_rag_prototype/api/routes/documents.py`)
- Ingestion endpoints → Database sessions: gets sessions (evidence: `src/document_rag_prototype/api/routes/ingestion.py`)
- Ingestion endpoints → ORM models: reads and writes (evidence: `src/document_rag_prototype/api/routes/ingestion.py`)
- Ingestion endpoints → Runtime config: gets upload path (evidence: `src/document_rag_prototype/api/routes/ingestion.py`)
- Ingestion endpoints → Extract and chunk: extracts and chunks (evidence: `src/document_rag_prototype/api/routes/ingestion.py`)
- Ingestion endpoints → Embedding service: embeds chunks (evidence: `src/document_rag_prototype/api/routes/ingestion.py`)
- Search endpoint → Database sessions: gets session (evidence: `src/document_rag_prototype/api/routes/rag.py`)
- Search endpoint → Vector retrieval: requests matches (evidence: `src/document_rag_prototype/api/routes/rag.py`)
- Search endpoint → Answer generation: requests answer (evidence: `src/document_rag_prototype/api/routes/rag.py`)
- Vector retrieval → Embedding service: embeds query (evidence: `src/document_rag_prototype/services/retrieval_service.py`)
- Vector retrieval → PostgreSQL / pgvector: queries vectors (evidence: `src/document_rag_prototype/services/retrieval_service.py`)
- Answer generation → OpenAI API: generates answer (evidence: `src/document_rag_prototype/services/generation_service.py`)
- Embedding service → OpenAI API: creates embeddings (evidence: `src/document_rag_prototype/services/embedding_service.py`)
- Database sessions → PostgreSQL / pgvector: connects (evidence: `README.md`)
- Health checks → Database sessions: checks database (evidence: `src/document_rag_prototype/api/routes/health.py`)
- API schemas → Search endpoint: validates requests (evidence: `src/document_rag_prototype/api/routes/rag.py`)
