# t-hara-coretec/rag_demo_20250424 architecture

> Architecture diagram of the GitHub repository t-hara-coretec/rag_demo_20250424, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/t-hara-coretec/rag_demo_20250424
- Repository: https://github.com/t-hara-coretec/rag_demo_20250424

## Overview

##### Project type and purpose
- This is a full‑stack chat application with Retrieval‑Augmented Generation (RAG).
- Purpose: Provide an interactive chat interface where user queries can be answered directly by an AI model or enriched with information retrieved from PDF documents.

##### File structure
- Top‑level components:
- chat_app.py, chat_app.html, chat_app.ts: main backend entrypoint and frontend assets
- rag_utils/: RAG implementation modules (pdf_processor, vector_store, rag_service, web_processor)
- datas/: PDF document store for ingestion
- chroma_db/: persistent vector store database (ChromaDB)
- Support scripts:
- create_flowchart.py / create_png_flowchart.py: tooling to generate flowcharts
- run.sh: startup script
- Test and cache directories for unit tests and web caching
- Configuration:
- rag_requirements.txt: Python dependencies
- run.sh: launch command

##### Extract key architecture hints from the README
- Three RAG components in rag_utils: PDF processing → vector store → RAG service
- The backend serves an HTML+TypeScript frontend at http://localhost:8000
- AI model integration using pydantic‑ai

##### Main components
a. Frontend (Browser):
- HTML/TypeScript client
- UI elements for chat input, RAG toggle
b. Backend (Python Application Server):
- HTTP server (chat_app.py) exposing REST or WebSocket endpoints
- Chat controller/orchestrator that receives requests from frontend
- Agent integration with AI model (pydantic‑ai)
c. RAG Pipeline:
- PDF Processor (rag_utils/pdf_processor.py): extract & chunk text
- Vector Store (rag_utils/vector_store.py): interface to ChromaDB
- RAG Service (rag_utils/rag_service.py): coordinate retrieval + augmentation
- Optional: Web Processor (rag_utils/web_processor.py) for fetching web pages
d. Data Stores:
- ChromaDB (chroma_db/chroma.sqlite3): stores embeddings & metadata
- Datas folder: source PDF documents
- Web cache: local JSON cache of fetched web pages
e. External Dependencies:
- AI Model API (pydantic‑ai)
- Chromadb library

##### Relationships & data flows
1. User submits a message in the frontend
2. Frontend calls backend chat endpoint
3. Backend determines if RAG is enabled
– If disabled: pass query directly to AI model, return response
– If enabled:
a. Invoke PDF Processor to read & chunk docs from datas/
b. Store or load chunks into Vector Store (ChromaDB)
c. RAG Service queries vector store for top‑k relevant chunks
d. Combine user query + retrieved chunks, call AI model
e. Return enriched response to frontend
4. Backend may persist logs to server_log.txt

##### Architectural patterns & design principles
- Layered architecture: Presentation (frontend) → Application (chat_app.py) → Domain/RAG modules → Persistence (ChromaDB)
- Separation of concerns: PDF ingestion, storage, retrieval, and chat orchestration are in distinct modules
- Stateful vs. stateless: Backend is stateless per request, state (embeddings) is in ChromaDB
- Extensibility: Web processor can be swapped in/out, AI model is configurable

- Clear, human‑readable labels on all components
- A note indicating configuration points (e.g., toggle RAG, model selection)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Browser)"
        direction TB
        FE_HTML["chat_app.html"]:::frontend
        FE_TS["chat_app.ts"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Python Application Server)"
        direction TB
        BE_SERVER["chat_app.py"]:::backend
        BE_DECISION{"RAG Enabled?"}:::decision
        BE_SERVER --> BE_DECISION
    end

    %% RAG Pipeline Subgraph
    subgraph "RAG Pipeline" 
        direction TB
        PDF_PROC["rag_utils/pdf_processor.py"]:::backend
        VEC_STORE["rag_utils/vector_store.py"]:::backend
        RAG_SVC["rag_utils/rag_service.py"]:::backend
        WEB_PROC["rag_utils/web_processor.py"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        DATAS["datas/"]:::datastore
        CHROMADB[(ChromaDB\nchroma.sqlite3)]:::datastore
        WEB_CACHE["web_cache/"]:::datastore
        LOGS["server_log.txt"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AI_MODEL["pydantic‑ai API"]:::external
        CHROMA_LIB["Chromadb Library"]:::external
    end

    %% Application Scripts & Config
    subgraph "Support Scripts & Config"
        direction TB
        SCRIPT_FLOW["create_flowchart.py"]:::support
        SCRIPT_PNG["create_png_flowchart.py"]:::support
        SCRIPT_RUN["run.sh"]:::support
        REQ["rag_requirements.txt"]:::support
    end

    %% Legend or Config Note
    NOTE["Note: Toggle RAG in chat_app.py\nConfigure model selection here"]:::note

    %% Connections
    User["User"]:::user --> FE_HTML
    FE_HTML --> FE_TS
    FE_TS -->|"HTTP Request / WebSocket"| BE_SERVER
    BE_DECISION -->|No| AI_MODEL
    AI_MODEL -->|"Response"| BE_SERVER
    BE_DECISION -->|Yes| PDF_PROC
    PDF_PROC -->|"Chunks"| VEC_STORE
    VEC_STORE -->|"Store/Retrieve embeddings"| CHROMADB
    VEC_STORE --> RAG_SVC
    WEB_PROC --> RAG_SVC
    DATAS --> PDF_PROC
    RAG_SVC -->|"Retrieve top‑k chunks"| VEC_STORE
    RAG_SVC -->|"Combined prompt"| AI_MODEL
    AI_MODEL -->|"Enriched response"| RAG_SVC
    RAG_SVC --> BE_SERVER
    BE_SERVER -->|"Logs"| LOGS

    BE_SERVER --> SCRIPT_RUN
    SCRIPT_RUN --> SCRIPT_FLOW
    SCRIPT_RUN --> SCRIPT_PNG
    BE_SERVER --> REQ

    NOTE -.-> BE_DECISION

    %% Click Events
    click FE_HTML "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/chat_app.html"
    click FE_TS "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/chat_app.ts"
    click BE_SERVER "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/chat_app.py"
    click PDF_PROC "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/rag_utils/pdf_processor.py"
    click VEC_STORE "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/rag_utils/vector_store.py"
    click RAG_SVC "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/rag_utils/rag_service.py"
    click WEB_PROC "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/rag_utils/web_processor.py"
    click DATAS "https://github.com/t-hara-coretec/rag_demo_20250424/tree/main/datas/"
    click CHROMADB "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/chroma_db/chroma.sqlite3"
    click WEB_CACHE "https://github.com/t-hara-coretec/rag_demo_20250424/tree/main/web_cache/"
    click SCRIPT_FLOW "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/create_flowchart.py"
    click SCRIPT_PNG "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/create_png_flowchart.py"
    click SCRIPT_RUN "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/run.sh"
    click REQ "https://github.com/t-hara-coretec/rag_demo_20250424/blob/main/rag_requirements.txt"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#0366d6,color:#0366d6
    classDef backend fill:#d4edda,stroke:#28a745,color:#155724
    classDef datastore fill:#ffe5b4,stroke:#e67e22,color:#b85400
    classDef external fill:#e0bbe4,stroke:#9b59b6,color:#512b58
    classDef support fill:#f0f0f0,stroke:#7f8c8d,color:#2c3e50
    classDef decision fill:#f8f9fa,stroke:#6c757d,color:#343a40
    classDef note fill:#fff3cd,stroke:#ffeeba,color:#856404
    classDef user fill:#ffffff,stroke:#000000,color:#000000

    class User user
```
