# d-nithinteja/ragforge architecture

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

- Interactive diagram: https://gitdiagram.com/d-nithinteja/ragforge
- Repository: https://github.com/d-nithinteja/ragforge

## Overview

#### 1. Purpose and Runtime Entry Points
RAGForge is an API-first, multi-tenant multimodal RAG system: users upload documents, asynchronously ingest text/tables/images, then query scoped document collections through streaming chat. FastAPI starts from `src/ragforge/main.py`; repository-level launch support is also present in `main.py`. Route aggregation is centralized in `src/ragforge/routes/index.py`.

#### 2. API, Authentication, and Tenant Boundary
HTTP routes expose authentication, file lifecycle, processing, and conversations. JWT authentication and database-session injection establish the authenticated user boundary before service execution. User ownership must flow through document, chunk, and conversation operations to enforce isolation.
- `src/ragforge/routes/auth_routes.py`
- `src/ragforge/routes/file_routes.py`
- `src/ragforge/routes/conversation_routes.py`
- `src/ragforge/dependencies/auth.py`

#### 3. Relational Metadata and Conversation State
SQLAlchemy models persist users, uploaded documents, chunk metadata, conversations, and messages. Documents/chunks track ingestion state and vector linkage; conversations retain selected document IDs and message history. The ORM is designed for SQLite or PostgreSQL, with sessions supplied at request boundaries.
- `src/ragforge/db/base.py`
- `src/ragforge/db/session.py`
- `src/ragforge/models/document.py`
- `src/ragforge/models/chunk.py`
- `src/ragforge/models/conversation.py`

#### 4. Upload and Ingestion Pipeline
File APIs delegate storage and processing orchestration to services. Processing runs as FastAPI background work rather than a separate queue. The ingestion stage partitions supported files through Unstructured, classifies multimodal elements, then prepares text, table, and image content for chunking/summarization. This is the primary boundary between raw uploaded files and retrieval-ready records.
- `src/ragforge/services/file_service.py`
- `src/ragforge/services/process_service.py`
- `src/ragforge/services/ingestion_service.py`
- `src/ragforge/services/unstructured_service.py`
- `src/ragforge/routes/process_routes.py`

#### 5. Multimodal Enrichment and Hybrid Indexing
Chunks preserve original content in a DocStore-oriented layer while generated summaries become embedded vector records. Text/table summaries use the configured LLM; image processing uses a vision-capable model and base64-oriented content handling. Vector IDs connect SQL chunk metadata to ChromaDB embeddings, allowing metadata filtering and original-content resolution.
- `src/ragforge/services/chunk_service.py`
- `src/ragforge/services/document_service.py`
- `src/ragforge/services/llm_service.py`
- `src/ragforge/services/vector_service.py`

#### 6. Retrieval-Augmented Conversation Flow
For an authenticated conversation question, retrieval searches vectorized summaries using user and optional conversation-document scope, then resolves originals for high-fidelity context. The RAG chain combines retrieved context, bounded recent history, and system prompts; final assistant messages and citations are persisted against the conversation.
- `src/ragforge/services/retrieval_service.py`
- `src/ragforge/services/rag_chain.py`
- `src/ragforge/services/conversation_service.py`
- `src/ragforge/models/message.py`
- `src/ragforge/config/prompts.py`

#### 7. Streaming and External Infrastructure
Generation is token-streamed over SSE, including handling for reasoning tokens and Mermaid sanitization. Material external dependencies are Ollama (default pluggable text/vision LLM backend), Sentence-Transformers embeddings, Unstructured high-resolution parsing, ChromaDB vector storage, and SQLite/PostgreSQL relational storage. Environment-backed Pydantic settings configure these runtime integrations, limits, secrets, and model choices.
- `src/ragforge/services/streaming_service.py`
- `src/ragforge/config/environment.py`
- `src/ragforge/config/constants.py`

Main entry points: [`src/ragforge/db/session.py`](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/db/session.py) (SQLAlchemy session), [`src/ragforge/routes/index.py`](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/index.py) (Route aggregation), [`src/ragforge/routes/conversation_routes.py`](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/conversation_routes.py) (Conversation APIs), [`src/ragforge/services/chunk_service.py`](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/chunk_service.py) (Chunk & document service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API boundary"]
  node_app["FastAPI app<br/>application entry<br/>[main.py]"]
  node_routes["Route aggregation<br/>router<br/>[index.py]"]
  node_auth["JWT &amp; session dependency<br/>auth boundary<br/>[auth.py]"]
  node_file_api["File APIs<br/>HTTP routes<br/>[file_routes.py]"]
  node_process_api["Processing APIs<br/>HTTP routes<br/>[process_routes.py]"]
  node_conversation_api["Conversation APIs<br/>HTTP routes"]
end

subgraph group_data["Metadata &amp; state"]
  node_orm[("SQLAlchemy session<br/>relational access<br/>[session.py]")]
  node_domain_models["Documents, chunks &amp; conversations<br/>ORM models<br/>[document.py]"]
end

subgraph group_ingest["Ingestion pipeline"]
  node_file_service["File lifecycle service<br/>[file_service.py]"]
  node_process_service["Background processing<br/>orchestrator<br/>[process_service.py]"]
  node_ingestion["Multimodal ingestion<br/>pipeline stage"]
  node_unstructured["Unstructured parsing<br/>parser adapter"]
  node_chunking["Chunk &amp; document service<br/>enrichment service<br/>[chunk_service.py]"]
end

subgraph group_rag["Retrieval &amp; generation"]
  node_retrieval["Scoped retrieval<br/>retrieval service"]
  node_rag_chain["RAG chain<br/>generation orchestrator<br/>[rag_chain.py]"]
  node_conversation_service["Conversation service<br/>state service"]
  node_streaming["SSE streaming<br/>streaming service"]
end

subgraph group_infra["Runtime infrastructure"]
  node_vector[("ChromaDB vector index<br/>vector storage<br/>[vector_service.py]")]
  node_llm{{"LLM &amp; embeddings<br/>AI backends<br/>[llm_service.py]"}}
  node_settings["Environment settings<br/>runtime configuration<br/>[environment.py]"]
end

node_app -->|"mounts"| node_routes
node_routes -->|"exposes"| node_file_api
node_routes -->|"exposes"| node_process_api
node_routes -->|"exposes"| node_conversation_api
node_file_api -->|"requires"| node_auth
node_conversation_api -->|"requires"| node_auth
node_auth -->|"injects"| node_orm
node_file_api -->|"delegates"| node_file_service
node_process_api -->|"starts"| node_process_service
node_file_service -->|"persists uploads"| node_orm
node_process_service -->|"orchestrates"| node_ingestion
node_ingestion -->|"partitions files"| node_unstructured
node_ingestion -->|"sends elements"| node_chunking
node_chunking -->|"writes chunk metadata"| node_orm
node_chunking -->|"indexes summaries"| node_vector
node_chunking -->|"summarizes content"| node_llm
node_conversation_api -->|"delegates"| node_conversation_service
node_conversation_service -->|"queries with scope"| node_retrieval
node_retrieval -->|"searches summaries"| node_vector
node_retrieval -->|"resolves originals"| node_orm
node_conversation_service -->|"builds answer"| node_rag_chain
node_rag_chain -->|"generates"| node_llm
node_conversation_service -->|"persists history"| node_orm
node_conversation_api -->|"streams SSE"| node_streaming
node_streaming -->|"streams tokens"| node_rag_chain
node_settings -.->|"configures"| node_orm
node_settings -.->|"configures"| node_vector
node_settings -.->|"configures"| node_llm

click node_app "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/main.py"
click node_routes "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/index.py"
click node_auth "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/dependencies/auth.py"
click node_file_api "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/file_routes.py"
click node_process_api "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/process_routes.py"
click node_conversation_api "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/conversation_routes.py"
click node_orm "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/db/session.py"
click node_domain_models "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/models/document.py"
click node_file_service "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/file_service.py"
click node_process_service "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/process_service.py"
click node_ingestion "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/ingestion_service.py"
click node_unstructured "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/unstructured_service.py"
click node_chunking "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/chunk_service.py"
click node_retrieval "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/retrieval_service.py"
click node_rag_chain "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/rag_chain.py"
click node_conversation_service "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/conversation_service.py"
click node_streaming "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/streaming_service.py"
click node_vector "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/vector_service.py"
click node_llm "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/llm_service.py"
click node_settings "https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/config/environment.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_app,node_routes,node_auth,node_file_api,node_process_api,node_conversation_api toneBlue
class node_orm,node_domain_models toneAmber
class node_file_service,node_process_service,node_ingestion,node_unstructured,node_chunking toneMint
class node_retrieval,node_rag_chain,node_conversation_service,node_streaming toneRose
class node_vector,node_llm,node_settings toneIndigo
```

## Components

### API boundary

Authenticated HTTP entry points and route composition.

- [FastAPI app](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/main.py): application entry · `src/ragforge/main.py`
- [Route aggregation](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/index.py): router · `src/ragforge/routes/index.py`
- [JWT & session dependency](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/dependencies/auth.py): auth boundary · Establishes authenticated user and database session per request. · `src/ragforge/dependencies/auth.py`
- [File APIs](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/file_routes.py): HTTP routes · `src/ragforge/routes/file_routes.py`
- [Processing APIs](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/process_routes.py): HTTP routes · `src/ragforge/routes/process_routes.py`
- [Conversation APIs](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/routes/conversation_routes.py): HTTP routes · `src/ragforge/routes/conversation_routes.py`

### Metadata & state

Tenant-owned relational records and conversation state.

- [SQLAlchemy session](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/db/session.py): relational access · Supports SQLite or PostgreSQL request-scoped persistence. · `src/ragforge/db/session.py`
- [Documents, chunks & conversations](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/models/document.py): ORM models · Stores ownership, ingestion state, vector links, selected documents, and messages. · `src/ragforge/models/document.py`

### Ingestion pipeline

Background processing turns uploads into retrieval-ready chunks.

- [File lifecycle service](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/file_service.py): service · `src/ragforge/services/file_service.py`
- [Background processing](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/process_service.py): orchestrator · Runs ingestion as FastAPI background work. · `src/ragforge/services/process_service.py`
- [Multimodal ingestion](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/ingestion_service.py): pipeline stage · Classifies parsed text, tables, and images for enrichment. · `src/ragforge/services/ingestion_service.py`
- [Unstructured parsing](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/unstructured_service.py): parser adapter · `src/ragforge/services/unstructured_service.py`
- [Chunk & document service](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/chunk_service.py): enrichment service · Preserves originals while preparing multimodal chunks and summaries. · `src/ragforge/services/chunk_service.py`

### Retrieval & generation

Scoped retrieval, context assembly, and streamed answers.

- [Scoped retrieval](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/retrieval_service.py): retrieval service · Filters vector search by user and optional conversation documents. · `src/ragforge/services/retrieval_service.py`
- [RAG chain](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/rag_chain.py): generation orchestrator · Combines retrieved originals, prompts, and bounded history. · `src/ragforge/services/rag_chain.py`
- [Conversation service](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/conversation_service.py): state service · Persists assistant messages and citations. · `src/ragforge/services/conversation_service.py`
- [SSE streaming](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/streaming_service.py): streaming service · Streams generation tokens and sanitizes Mermaid output. · `src/ragforge/services/streaming_service.py`

### Runtime infrastructure

Configured external persistence and AI integrations.

- [ChromaDB vector index](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/vector_service.py): vector storage · Stores summary embeddings keyed by vector IDs. · `src/ragforge/services/vector_service.py`
- [LLM & embeddings](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/services/llm_service.py): AI backends · Ollama text/vision models and Sentence-Transformers embeddings. · `src/ragforge/services/llm_service.py`
- [Environment settings](https://github.com/d-nithinteja/ragforge/blob/main/src/ragforge/config/environment.py): runtime configuration · Configures models, secrets, limits, and infrastructure. · `src/ragforge/config/environment.py`

## Connections

- FastAPI app → Route aggregation: mounts
- Route aggregation → File APIs: exposes
- Route aggregation → Processing APIs: exposes
- Route aggregation → Conversation APIs: exposes
- File APIs → JWT & session dependency: requires
- Conversation APIs → JWT & session dependency: requires
- JWT & session dependency → SQLAlchemy session: injects
- File APIs → File lifecycle service: delegates
- Processing APIs → Background processing: starts
- File lifecycle service → SQLAlchemy session: persists uploads
- Background processing → Multimodal ingestion: orchestrates
- Multimodal ingestion → Unstructured parsing: partitions files
- Multimodal ingestion → Chunk & document service: sends elements
- Chunk & document service → SQLAlchemy session: writes chunk metadata
- Chunk & document service → ChromaDB vector index: indexes summaries
- Chunk & document service → LLM & embeddings: summarizes content
- Conversation APIs → Conversation service: delegates
- Conversation service → Scoped retrieval: queries with scope
- Scoped retrieval → ChromaDB vector index: searches summaries
- Scoped retrieval → SQLAlchemy session: resolves originals
- Conversation service → RAG chain: builds answer
- RAG chain → LLM & embeddings: generates
- Conversation service → SQLAlchemy session: persists history
- Conversation APIs → SSE streaming: streams SSE
- SSE streaming → RAG chain: streams tokens
- Environment settings → SQLAlchemy session: configures
- Environment settings → ChromaDB vector index: configures
- Environment settings → LLM & embeddings: configures