d-nithinteja/ragforge

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