# lelekhoa1812/studybuddy architecture

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

- Interactive diagram: https://gitdiagram.com/lelekhoa1812/studybuddy
- Repository: https://github.com/lelekhoa1812/studybuddy

## Overview

##### Project Type & Purpose
- EdSummariser (StudyBuddy) is a modular, full-stack Retrieval-Augmented Generation (RAG) application built in Python with FastAPI. Its primary function is to ingest user documents (PDF/DOCX), index them via embeddings, and answer user queries by retrieving context and composing answers via LLMs, while maintaining per‐user memory.

##### Top-Level Components
A. FastAPI App (app.py + routes/)
- Central orchestration, HTTP interface
- Routes grouped by function: auth, projects, upload, data, chat, report, health
B. Ingestion Subsystem (utils/ingestion + helpers/pages)
- PDF/DOCX parser → image extraction → optional BLIP captioning
- Chunker (cards) → embedder (sentence-transformers) → storage in vector DB
C. RAG Store & Vector Search (utils/rag + MongoDB)
- Embeddings pipeline
- Storage backend: Mongo Atlas (with Atlas Vector Search) or local cosine index
D. Retrieval & Relevance Classification (routes/chat + utils/api/rotator/router)
- Filename detection → NVIDIA relevance classifier → restrict vector queries
- Retry logic & summary fallbacks
E. Memory System (memo/)
- LRU per-user memory summaries
- Components: context, conversation, history, sessions, planning, retrieval
F. Reasoning & LLM Integration (utils/api + utils/service)
- Key rotation (NVIDIA_API_1..5 / GEMINI_* ) via api/rotator/router
- Summarizer, PDF report generator in service/
G. Data Storage & Config
- MongoDB document store + vector index
- Config via environment (MONGO_URI, vector index flags, model overrides)

##### Data-Flow Workflow (detailed backend focus)
1) Upload Endpoint (/upload)
→ **app.py** calls ingestion orchestrator
→ utils/ingestion/parser.py extracts pages
→ helpers/pages.py merges images + captions (BLIP via utils/api)
→ ingestion/chunker.py splits into cards
→ rag/embeddings.py computes embeddings
→ rag/rag.py stores vectors + metadata in MongoDB
2) Chat Endpoint (/chat)
→ routes/chats.py receives question + user context
→ memo/session.py loads recent-memory summaries
→ namer.py detects filenames in query
→ utils/api/router.py calls NVIDIA classifier for per-file relevance
→ rag/rag.py performs vector search with restricted file list
- on zero hits → retry phases → fallback to file-level summaries
→ Compose prompt: context + retrieved chunks + memory + question
→ utils/api/router.py dispatch to LLM (Gemini/NVIDIA) with key rotation
→ routes/chats.py returns answer + sources + relevant_files
→ memo/history.py + memo/conversation.py update memory

3) Report Generation (/report)
→ routes/reports.py applies Gemini CoT filter via utils/service/summarizer.py
→ utils/service/pdf.py renders PDF

##### Architectural Patterns & Design Principles
- Modular Monolith: separate concerns into directories (routes, utils, memo, helpers)
- Pipeline Architecture for ingestion & retrieval
- Layered approach:
1) HTTP Layer (FastAPI routes)
2) Orchestration Layer (app.py, helpers/setup.py)
3) Domain Services (utils/ingestion, utils/rag, utils/service)
4) Data Layer (MongoDB + vector index)
- External Service Integration: BLIP for captions, NVIDIA for classification, LLM endpoints

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% HTTP Layer
    subgraph "HTTP Layer"
        direction TB
        App["FastAPI App\napp.py"]:::http
        Setup["App Setup\nhelpers/setup.py"]:::http
        Auth["Auth Route\nroutes/auth.py"]:::http
        Projects["Projects Route\nroutes/projects.py"]:::http
        Files["Files Upload Route\nroutes/files.py"]:::http
        Search["Search Route\nroutes/search.py"]:::http
        Chats["Chat Route\nroutes/chats.py"]:::http
        Reports["Report Route\nroutes/reports.py"]:::http
        SessionsRoute["Sessions Route\nroutes/sessions.py"]:::http
        Health["Health Route\nroutes/health.py"]:::http
    end

    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline" 
        direction TB
        Parser["Document Parser\nutils/ingestion/parser.py"]:::ingest
        Caption["Captioning (BLIP)\nutils/ingestion/caption.py"]:::ingest
        Pages["Page Merge & Images\nhelpers/pages.py"]:::ingest
        Chunker["Chunker\nutils/ingestion/chunker.py"]:::ingest
        Embedder["Embeddings\nutils/rag/embeddings.py"]:::ingest
        StoreVec["Store Vectors\nutils/rag/rag.py"]:::ingest
    end

    %% Retrieval & Classification
    subgraph "Retrieval & Classification"
        direction TB
        Namer["Filename Detection\nhelpers/namer.py"]:::retrieval
        Classifier["Relevance Classifier\nutils/api/router.py"]:::retrieval
        Rotator["API Key Rotator\nutils/api/rotator.py"]:::retrieval
    end

    %% Memory Subsystem
    subgraph "Memory Subsystem"
        direction TB
        MemoCore["Core Memory\nmemo/core.py"]:::memory
        MemoSession["Session & LRU\nmemo/session.py\nmemo/sessions.py"]:::memory
        Conversation["Conversation\nmemo/conversation.py"]:::memory
        History["History\nmemo/history.py"]:::memory
        Context["Context\nmemo/context.py"]:::memory
        Planning["Planning\nmemo/planning.py\nmemo/retrieval.py"]:::memory
        PlanExec["Plan Execution\nmemo/plan/execution.py\nmemo/plan/intent.py\nmemo/plan/strategy.py"]:::memory
        Persist["Persistent Storage\nmemo/persistent.py\nmemo/consolidation.py"]:::memory
        NvidiaMem["NVIDIA Memory Logic\nmemo/nvidia.py"]:::memory
    end

    %% Reasoning & LLM
    subgraph "Reasoning & LLM"
        direction TB
        ServiceCommon["Common Service\nutils/service/common.py"]:::reason
        Summarizer["Summarizer\nutils/service/summarizer.py"]:::reason
        PDFGen["PDF Report Gen\nutils/service/pdf.py"]:::reason
    end

    %% Storage
    subgraph "Data Storage"
        direction TB
        MongoDoc[(MongoDB\nDocument Store)]:::storage
        MongoVec[(MongoDB Vector Index)]:::storage
    end

    %% External Services
    subgraph "External APIs"
        direction TB
        BLIP["BLIP API"]:::external
        NVIDIA["NVIDIA API"]:::external
        Gemini["Gemini LLM"]:::external
    end

    %% Data Flow: Upload
    Files -->|"POST /upload"| Parser
    Parser --> Pages
    Pages --> Caption
    Caption --> Chunker
    Chunker --> Embedder
    Embedder --> StoreVec
    StoreVec --> MongoVec
    StoreVec --> MongoDoc

    %% Data Flow: Chat
    Chats --> MemoSession
    MemoSession --> Context
    Chats --> Namer
    Namer --> Classifier
    Classifier --> Rotator
    Rotator --> MongoVec
    MongoVec -->|"vector search"| StoreVec
    StoreVec -->|"on zero hits fallback"| Persist
    Persist --> Context
    Context --> Summarizer
    Summarizer --> MongoDoc
    Summarizer --> PDFGen
    Summarizer --> Gemini
    Gemini --> Chats
    Chats --> History
    Chats --> Conversation

    %% Reasoning Flow
    Rotator --> GPU["GPU Service"]:::external
    GPU --> Gemini

    %% Health & Config
    Health --> App
    Setup --> App

    %% Class & colors
    classDef http fill:#D6E9F8,stroke:#4A90E2;
    classDef ingest fill:#D0E8FF,stroke:#0074D9;
    classDef retrieval fill:#E3F9E5,stroke:#2ECC40;
    classDef memory fill:#FFE8D6,stroke:#FF851B;
    classDef reason fill:#F3E5FF,stroke:#B10DC9;
    classDef storage fill:#F0F0F0,stroke:#AAAAAA;
    classDef external fill:#FFFFFF,stroke:#AAAAAA,stroke-dasharray: 2 2;

    %% Click events
    click App "https://github.com/lelekhoa1812/studybuddy/blob/main/app.py"
    click Setup "https://github.com/lelekhoa1812/studybuddy/blob/main/helpers/setup.py"
    click Auth "https://github.com/lelekhoa1812/studybuddy/blob/main/routes/auth.py"
    click Projects "https://github.com/lelekhoa1812/studybuddy/blob/main/routes/projects.py"
    click Files "https://github.com/lelekhoa1812/studybuddy/blob/main/routes/files.py"
    click Search "https://github.com/lelekhoa1812/studybuddy/blob/main/routes/search.py"
    click Chats "https://github.com/lelekhoa1812/studybuddy/blob/main/routes/chats.py"
    click Reports "https://github.com/lelekhoa1812/studybuddy/blob/main/routes/reports.py"
    click SessionsRoute "https://github.com/lelekhoa1812/studybuddy/blob/main/routes/sessions.py"
    click Health "https://github.com/lelekhoa1812/studybuddy/blob/main/routes/health.py"
    click Parser "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/ingestion/parser.py"
    click Caption "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/ingestion/caption.py"
    click Pages "https://github.com/lelekhoa1812/studybuddy/blob/main/helpers/pages.py"
    click Chunker "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/ingestion/chunker.py"
    click Embedder "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/rag/embeddings.py"
    click StoreVec "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/rag/rag.py"
    click Namer "https://github.com/lelekhoa1812/studybuddy/blob/main/helpers/namer.py"
    click Classifier "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/api/router.py"
    click Rotator "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/api/rotator.py"
    click MemoCore "https://github.com/lelekhoa1812/studybuddy/blob/main/memo/core.py"
    click MemoSession "https://github.com/lelekhoa1812/studybuddy/blob/main/memo/session.py"
    click Conversation "https://github.com/lelekhoa1812/studybuddy/blob/main/memo/conversation.py"
    click History "https://github.com/lelekhoa1812/studybuddy/blob/main/memo/history.py"
    click Context "https://github.com/lelekhoa1812/studybuddy/blob/main/memo/context.py"
    click Planning "https://github.com/lelekhoa1812/studybuddy/blob/main/memo/planning.py"
    click PlanExec "https://github.com/lelekhoa1812/studybuddy/blob/main/memo/plan/execution.py"
    click Persist "https://github.com/lelekhoa1812/studybuddy/blob/main/memo/persistent.py"
    click NvidiaMem "https://github.com/lelekhoa1812/studybuddy/blob/main/memo/nvidia.py"
    click ServiceCommon "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/service/common.py"
    click Summarizer "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/service/summarizer.py"
    click PDFGen "https://github.com/lelekhoa1812/studybuddy/blob/main/utils/service/pdf.py"
```
