# nkmohit/minimal-rag-backend architecture

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

- Interactive diagram: https://gitdiagram.com/nkmohit/minimal-rag-backend
- Repository: https://github.com/nkmohit/minimal-rag-backend

## Overview

##### Project type and purpose
- This is a minimal RAG (Retrieval-Augmented Generation) backend service implemented in Python using FastAPI.
- Its purpose is to provide a clean, production-oriented pipeline for ingesting documents, storing embeddings in Chroma, retrieving semantically relevant chunks, and generating answers via the Gemini LLM.

##### File structure
- Top-level files:
- main.py: FastAPI application entrypoint, defines HTTP endpoints.
- Dockerfile / .dockerignore: containerization config.
- requirements.txt: Python dependencies.
- rag/ directory: the core pipeline modules, each with a single responsibility:
- loader.py – document upload & text extraction
- embeddings.py – text chunking + embedding generation (Sentence Transformers)
- generation.py – semantic retrieval (Chroma) + LLM answer generation (Gemini)

##### README for additional insights
- The README outlines the six-stage pipeline: Upload → Extraction → Chunking → Embeddings → Vector DB → Retrieval + LLM.
- Technology stack: FastAPI, Sentence Transformers, Chroma DB, Google Gemini via google-genai SDK.
- Persistence: local disk storage for uploaded docs and Chroma data (ephemeral unless volumes are mounted).

a. Main components:
1. Client (e.g. curl, Postman, frontend)
2. FastAPI Server (main.py)
3. Ingestion Modules (rag/loader.py)
4. Embedding Module (rag/embeddings.py)
5. Vector Store (Chroma)
6. Retrieval + LLM Generation Module (rag/generation.py)
7. External LLM Service (Google Gemini)
8. Local File Storage (for uploaded documents and persistent Chroma files)
b. Relationships & interactions:
- Client → FastAPI endpoints (/upload, /index, /query)
- /upload calls loader.py → stores raw file to disk
- /index triggers loader.py → splits/extracts text → embeddings.py → generates vectors → writes to Chroma
- /query invokes generation.py → queries Chroma for top-k chunks → calls external Gemini API → returns combined answer to client
- Chroma persists data on disk; Gemini is an external HTTP API
c. Architectural patterns & design principles:
- Single-Responsibility Modules: each rag/*.py file implements one stage
- Pipeline Flow: strictly linear processing stages
- Separation of concerns: HTTP layer (main.py), ingestion, embedding, retrieval/generation
- Local persistence for simplicity & portability
d. Key technologies & frameworks:
- FastAPI (HTTP server, dependency injection)
- Sentence Transformers (embeddings)
- Chroma DB (vector store)
- google-genai SDK (Gemini LLM)
- Docker for containerization

##### Final advice
- Key environment variables or config files (e.g. .env → GEMINI_API_KEY)
- Version or tech stack notes next to each component

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client\n(e.g., curl, Postman)"]:::client

    %% API Layer
    FastAPI["FastAPI App\n(main.py)"]:::api

    %% Processing Modules
    subgraph "Processing Modules"
        Loader["Loader Module\n(rag/loader.py)"]:::process
        Embedding["Embedding Module\n(rag/embeddings.py)"]:::process
        Generation["Retrieval + LLM Module\n(rag/generation.py)"]:::process
    end

    %% Storage
    subgraph "On-Disk Persistence"
        Disk["Local File Storage"]:::storage
        Chroma["Chroma DB\n(persistent vector store)"]:::storage
    end

    %% External Service
    Gemini["Google Gemini LLM\n(external API)"]:::external

    %% Data Flow
    Client -->|"HTTP /upload"| FastAPI
    FastAPI -->|"calls loader"| Loader
    Loader -->|"store raw docs"| Disk

    FastAPI -->|"HTTP /index"| Loader
    Loader -->|"extract & chunk"| Embedding
    Embedding -->|"generate & write vectors"| Chroma

    FastAPI -->|"HTTP /query"| Generation
    Generation -->|"retrieve chunks"| Chroma
    Generation -->|"call external API"| Gemini
    Gemini -->|"return LLM answer"| Generation
    Generation -->|"response"| FastAPI
    FastAPI -->|"HTTP response"| Client

    %% Click Events
    click FastAPI "https://github.com/nkmohit/minimal-rag-backend/blob/main/main.py"
    click Loader "https://github.com/nkmohit/minimal-rag-backend/blob/main/rag/loader.py"
    click Embedding "https://github.com/nkmohit/minimal-rag-backend/blob/main/rag/embeddings.py"
    click Generation "https://github.com/nkmohit/minimal-rag-backend/blob/main/rag/generation.py"
    click requirements "https://github.com/nkmohit/minimal-rag-backend/blob/main/requirements.txt"
    click Dockerfile "https://github.com/nkmohit/minimal-rag-backend/tree/main/Dockerfile"
    click dockerignore "https://github.com/nkmohit/minimal-rag-backend/blob/main/.dockerignore"
    click README "https://github.com/nkmohit/minimal-rag-backend/blob/main/README.md"

    %% Styles
    classDef client fill:#DDEEFF,stroke:#333,stroke-width:1px
    classDef api fill:#BBCCFF,stroke:#333,stroke-width:1px
    classDef process fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef storage fill:#FFEEAA,stroke:#333,stroke-width:1px
    classDef external fill:#FFCCCC,stroke:#333,stroke-width:1px
```
