# shahvir-w/document-rag-app architecture

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

- Interactive diagram: https://gitdiagram.com/shahvir-w/document-rag-app
- Repository: https://github.com/shahvir-w/document-rag-app

## Overview

##### Project Type and Purpose
- This is a full-stack Retrieval-Augmented Generation (RAG) application.
- Frontend: React + TypeScript (Vite, Tailwind) providing document upload, PDF/text viewing, chat UI.
- Backend: FastAPI serving REST endpoints, orchestrating ChromaDB indexing/queries and summarization via Celery tasks.
- Datastore: ChromaDB (SQLite), Redis as Celery broker/cache, Docker Compose for service orchestration.

##### File Structure
- Top-level directories:
- frontend/ – React app (src/components, services, public)
- backend/ – FastAPI app (app/api, app/services, app/tasks)
- chromadb/ – SQLite data file
- docker-compose.yml – defines services: backend API, Celery worker, Redis, (optionally ChromaDB service)
- The backend uses:
- “api” for REST endpoints (chat.py, documentUpload.py, textUpload.py)
- “services” for high-level logic (createChroma, createSummary, queryChroma)
- “tasks” for asynchronous jobs (celery_config, chroma_tasks)
- The frontend calls a single backend API and handles rendering and user interaction.

##### README Insights
- RAG workflow: user uploads → text is chunked & embedded in ChromaDB → user queries via chat UI → system retrieves relevant embeddings → LLM summarization/response.
- Uses Celery + Redis for offloading heavy processing.
- Docker Compose brings up: FastAPI server (port 5000), Celery workers, Redis, and ChromaDB persistence.

##### Defining Main Components
a. User & UI Layer
- Browser client interacts over HTTPS to the React frontend.
b. Frontend Application
- Vite-served React app components (Chat, DocumentView, Compartments).
- API service module in src/services/api.ts for HTTP calls.
c. API Gateway / Backend
- FastAPI application (app/main.py) exposing endpoints.
- Endpoints in app/api.* handle upload and chat routes.
- Config module (config.py) for environment settings.
d. Service Layer
- app/services:
- createChroma: chunking & embedding document text → store in ChromaDB
- queryChroma: vector search to fetch relevant chunks
- createSummary: summarization/compartment logic
e. Task Queue
- Celery (app/tasks/*) with Redis broker & backend.
- Asynchronous jobs: chroma indexing, summarization tasks.
f. Data Stores & External Services
- ChromaDB (SQLite) as vector store.
- Redis for message brokering and caching.
- (Optionally) LLM provider’s external API if used for summarization/chat.

##### Relationships and Interactions
- Browser → Frontend (React) → HTTP → FastAPI
- FastAPI → synchronous calls to services.queryChroma for chat requests
- FastAPI → dispatch tasks to Celery (via Redis) for heavy processing (indexing/summarization)
- Celery Worker → access app/services implementations → read/write to ChromaDB → return results via Redis
- FastAPI → return final payload to frontend → UI update

##### Architectural Patterns & Design Principles
- Layered architecture: UI | API | Services | Data | Background Tasks
- Asynchronous task pattern: Celery + Redis decouples heavy compute from request-response cycle
- Modular separation: services vs. tasks vs. API vs. UI
- Single codebase orchestrated via Docker Compose for reproducible environments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        User["Browser"]:::user
        React["React Frontend"]:::frontend
    end
    User -->|HTTPS REST| React
    click React "https://github.com/shahvir-w/document-rag-app/tree/main/frontend/"
    
    %% Backend and Services within Docker Compose
    subgraph "Docker Compose"
        direction TB

        %% API Layer
        subgraph "API Layer"
            direction TB
            FastAPI["FastAPI Backend"]:::api
            click FastAPI "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/main.py"
            Config["config.py"]:::api
            click Config "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/config.py"

            subgraph "REST Endpoints"
                direction TB
                ChatAPI["chat.py"]:::api
                click ChatAPI "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/api/chat.py"
                DocAPI["documentUpload.py"]:::api
                click DocAPI "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/api/documentUpload.py"
                TextAPI["textUpload.py"]:::api
                click TextAPI "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/api/textUpload.py"
            end

            subgraph "Service Layer"
                direction TB
                CreateChroma["createChroma.py"]:::service
                click CreateChroma "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/services/createChroma.py"
                QueryChroma["queryChroma.py"]:::service
                click QueryChroma "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/services/queryChroma.py"
                Summary["createSummary.py"]:::service
                click Summary "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/services/createSummary.py"
            end
        end

        FastAPI -->|loads| Config
        FastAPI -->|"routes to"| ChatAPI
        FastAPI -->|"routes to"| DocAPI
        FastAPI -->|"routes to"| TextAPI

        ChatAPI -->|"calls"| CreateChroma
        DocAPI -->|"calls"| CreateChroma
        TextAPI -->|"calls"| CreateChroma

        ChatAPI -->|"calls"| QueryChroma
        ChatAPI -->|"calls"| Summary

        %% Redis Broker
        Redis["Redis"]:::data
        click Redis "https://github.com/shahvir-w/document-rag-app/blob/main/docker-compose.yml"

        FastAPI -->|enqueue job| Redis

        %% Worker Layer
        subgraph "Worker Layer"
            direction TB
            Worker["Celery Worker"]:::worker
            click Worker "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/tasks/celery_config.py"

            subgraph "Task Module"
                direction TB
                CeleryConfig["celery_config.py"]:::worker
                click CeleryConfig "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/tasks/celery_config.py"
                ChromaTasks["chroma_tasks.py"]:::worker
                click ChromaTasks "https://github.com/shahvir-w/document-rag-app/blob/main/backend/app/tasks/chroma_tasks.py"
            end
        end

        Redis -->|broker fetch & results| Worker
        Worker -->|"executes tasks"| ChromaTasks
        Worker -->|"executes tasks"| CeleryConfig

        %% Data Stores
        ChromaDB["ChromaDB (SQLite)"]:::data
        click ChromaDB "https://github.com/shahvir-w/document-rag-app/blob/main/chromadb/chroma.sqlite3"
        Worker -->|read/write vectors| ChromaDB
        FastAPI -->|sync vector search| ChromaDB

        %% External LLM
        LLM["External LLM API"]:::external
        Worker -->|HTTP API| LLM
    end

    %% Frontend Components
    React -->|"imports"| ChatComp
    ChatComp["Chat.tsx"]:::frontend
    click ChatComp "https://github.com/shahvir-w/document-rag-app/blob/main/frontend/src/components/Chat.tsx"
    React -->|"imports"| DocComp
    DocComp["DocumentView.tsx"]:::frontend
    click DocComp "https://github.com/shahvir-w/document-rag-app/blob/main/frontend/src/components/DocumentView.tsx"
    React -->|"imports"| CompartmentsComp
    CompartmentsComp["Compartments.tsx"]:::frontend
    click CompartmentsComp "https://github.com/shahvir-w/document-rag-app/blob/main/frontend/src/components/Compartments.tsx"
    React -->|"imports"| LandingComp
    LandingComp["LandingPage.tsx"]:::frontend
    click LandingComp "https://github.com/shahvir-w/document-rag-app/blob/main/frontend/src/components/LandingPage.tsx"
    React -->|"imports"| MainComp
    MainComp["MainView.tsx"]:::frontend
    click MainComp "https://github.com/shahvir-w/document-rag-app/blob/main/frontend/src/components/MainView.tsx"
    React -->|"uses API service"| ApiService
    ApiService["api.ts"]:::frontend
    click ApiService "https://github.com/shahvir-w/document-rag-app/blob/main/frontend/src/services/api.ts"

    %% Connections
    React -->|HTTP POST /chat| FastAPI

    %% Styles
    classDef user fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef frontend fill:#B3E5FC,stroke:#0288D1,color:#01579B;
    classDef api fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20;
    classDef service fill:#FFE0B2,stroke:#EF6C00,color:#E65100;
    classDef worker fill:#FFCCBC,stroke:#D84315,color:#BF360C;
    classDef data fill:#ECEFF1,stroke:#455A64,color:#263238;
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#6A1B9A;
```
