# tmullayanov/simple-rag architecture

> Architecture diagram of the GitHub repository tmullayanov/simple-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tmullayanov/simple-rag
- Repository: https://github.com/tmullayanov/simple-rag

## Overview

##### Main Components
- API Server: Represented by FastAPI and the endpoints defined within simple_rag/web/routes. This includes endpoints like chat creation, message sending, model updates, and possibly summarization.
- Chat Management: The module in simple_rag/chats provides the chat logic and maintains user sessions.
- RAG Model (QnA): The core logic for processing questions and retrieving answers is implemented in the simple_rag/models/qna_rag directory. This includes:
- Parser (assets and CSV parsing with csv_parser.py).
- Engine and memory management.
- Query handling and state management.
- LLM Integration: The simple_rag/llm directory (particularly groq.py) handles interactions with the Groq language model.
- Summarizer: An alternate or additional model for summarization housed in simple_rag/models/summarizer.
- Configuration & Logging: Global settings and configurations (e.g., environment variables, logging via simple_rag/logger.py and web/config.py) that tie the system pieces together.
- Demo and Testing: Demo HTML files and various Jupyter notebooks (rag_1.ipynb, rag_2_advanced.ipynb, rag_qna.ipynb) demonstrate the RAG approach, while the tests directory validates system components.

##### Out Relationships and Data Flow
- External User Interaction: External requests (via curl or a browser) enter the system through the FastAPI endpoints.
- API Layer: Once a request is received, the FastAPI controllers (in simple_rag/web/routes) route the calls to business logic components.
- Chat Manager: A request for creating or updating a chat is handled in simple_rag/chats, which instantiates sessions and maintains per-chat model instances.
- Model Invocation and Processing:
– For QnA tasks, the engine in simple_rag/models/qna_rag processes the CSV data (using csv_parser) to build an in-memory vector for retrieving answers.
– For generating responses, the system calls functions within simple_rag/llm (via groq.py) that interact with the Groq model.
– Summarizer components (if used) in simple_rag/models/summarizer apply additional processing.
- Return of Results: Processed responses and status (e.g., chat creation success, answer retrieval) are then returned to the user.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is split into distinct modules (web, chats, models, llm) that cleanly separate API handling, business logic, model processing, and integrations.
- Modularity: Each folder (e.g., models, chats, web) can be visualized as individual components with clear input and output flows.
- Extensibility: There is a clear design path for adding new models or updating current ones (as shown in the update_model endpoint).

##### Technologies and Frameworks
- Python (3.8+): Core language.
- FastAPI: API framework powering the web endpoints.
- Groq: The language model integration.
- CSV Parsing for QnA: In-memory vector building from static files.
- uv: For managing environment and running the server.
- Testing frameworks (implied by tests/ folder): For ensuring quality and correctness.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Client
    User["User / Client"]:::external

    %% API Layer
    API["API Server (FastAPI)"]:::api
    User -->|"request"| API

    %% Configuration & Logging Subgraph
    subgraph "Configuration & Logging"
        Config["Config (web/config.py)"]:::config
        Logger["Logger (logger.py)"]:::config
    end
    API ---|"uses"| Config
    API ---|"logs to"| Logger

    %% Chat Management
    Chat["Chat Manager"]:::chat
    API -->|"routes chat requests"| Chat

    %% Business Logic: QnA Model Subgraph
    subgraph "QnA Model (RAG)"
        Engine["Engine (engine.py)"]:::model
        Memory["Memory (memory.py)"]:::model
        ModelNode["Model (model.py)"]:::model
        State["State (state.py)"]:::model
        Store["Store (store.py)"]:::model
        Prompts["Prompts (prompts.py)"]:::model
        QnA["QnA (qna.py)"]:::model
        CSVParser["CSV Parser (csv_parser.py)"]:::model
    end

    %% LLM Integration
    LLM["LLM Integration (Groq)"]:::llm

    %% Summarizer Model
    Summarizer["Summarizer Model"]:::summarizer

    %% Demo & Testing Subgraph
    subgraph "Demo & Testing"
        DemoHTML["Demo (demo/)"]:::demo
        Notebook1["Notebook (rag_1.ipynb)"]:::demo
        Notebook2["Notebook (rag_2_advanced.ipynb)"]:::demo
        Notebook3["Notebook (rag_qna.ipynb)"]:::demo
        Tests["Tests (tests/)"]:::demo
    end

    %% Flow between Chat Manager and Model Components
    Chat -->|"invokes"| Engine
    Chat -->|"invokes"| Memory
    Chat -->|"invokes"| ModelNode
    Chat -->|"invokes"| State
    Chat -->|"invokes"| Store
    Chat -->|"invokes"| Prompts
    Chat -->|"invokes"| QnA
    Chat -->|"uses CSV"| CSVParser
    Chat -->|"calls"| LLM
    Chat -->|"optionally uses"| Summarizer

    %% Return flow
    Engine -->|"returns answer"| Chat
    Memory -->|"returns data"| Chat
    ModelNode -->|"returns model result"| Chat
    State -->|"returns state"| Chat
    Store -->|"returns store data"| Chat
    Prompts -->|"returns prompts"| Chat
    QnA -->|"returns QnA result"| Chat
    CSVParser -->|"returns parsed CSV"| Chat
    LLM -->|"returns LLM response"| Chat
    Summarizer -->|"returns summary"| Chat

    Chat -->|"response"| API
    API -->|"response"| User

    %% Click Events for API Server
    click API "https://github.com/tmullayanov/simple-rag/tree/master/simple_rag/web/routes"
    click Config "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/web/config.py"
    click Logger "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/logger.py"

    %% Click Event for Chat Manager
    click Chat "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/chats/chat.py"

    %% Click Events for QnA Model Components
    click Engine "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/models/qna_rag/engine.py"
    click Memory "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/models/qna_rag/memory.py"
    click ModelNode "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/models/qna_rag/model.py"
    click State "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/models/qna_rag/state.py"
    click Store "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/models/qna_rag/store.py"
    click Prompts "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/models/qna_rag/prompts.py"
    click QnA "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/models/qna_rag/qna.py"
    click CSVParser "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/models/qna_rag/parser/csv_parser.py"

    %% Click Event for LLM Integration
    click LLM "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/llm/groq.py"

    %% Click Event for Summarizer Model
    click Summarizer "https://github.com/tmullayanov/simple-rag/blob/master/simple_rag/models/summarizer/model.py"

    %% Click Events for Demo & Testing
    click DemoHTML "https://github.com/tmullayanov/simple-rag/tree/master/demo/"
    click Notebook1 "https://github.com/tmullayanov/simple-rag/blob/master/rag_1.ipynb"
    click Notebook2 "https://github.com/tmullayanov/simple-rag/blob/master/rag_2_advanced.ipynb"
    click Notebook3 "https://github.com/tmullayanov/simple-rag/blob/master/rag_qna.ipynb"
    click Tests "https://github.com/tmullayanov/simple-rag/tree/master/tests/"

    %% Styles
    classDef external fill:#ffe680,stroke:#333,stroke-width:2px;
    classDef api fill:#aee1f9,stroke:#333,stroke-width:2px;
    classDef chat fill:#c8facc,stroke:#333,stroke-width:2px;
    classDef model fill:#f9d1a9,stroke:#333,stroke-width:2px;
    classDef llm fill:#ffb3ba,stroke:#333,stroke-width:2px;
    classDef summarizer fill:#d3c0eb,stroke:#333,stroke-width:2px;
    classDef config fill:#d3e0ea,stroke:#333,stroke-width:2px;
    classDef demo fill:#f9e79f,stroke:#333,stroke-width:2px;
```
