# notvishwas/rag-agent architecture

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

- Interactive diagram: https://gitdiagram.com/notvishwas/rag-agent
- Repository: https://github.com/notvishwas/rag-agent

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **small full-stack web app** with:
- A **single-page frontend** (`public/index.html`) that includes:
- Document upload UI
- A bottom-left **chat widget**
- A **Node.js/Express backend** (`server.js`) that:
- Accepts uploads and stores file content
- Exposes REST endpoints for listing/deleting docs
- Implements a simple **RAG flow** by injecting all stored document text into a **Gemini** prompt
- An **external dependency**: **Google Gemini API** (model: `gemini-2.0-flash` per README)

Important architectural characteristic: **No vector DB / embeddings**. “Retrieval” here is effectively “use *all* uploaded docs as context” (in-memory) and ask Gemini to answer only from that context.

##### File structure signals (what maps to components)
From the tree:
- `server.js` → **Backend service** (Express routes, upload handling, Gemini integration, in-memory store)
- `public/index.html` → **Frontend UI** (Bootstrap + widget + API calls)
- `public/` → Static assets served by backend (likely `express.static`)
- `package.json` → Runtime + scripts (`npm start`, `npm run dev`)
- `uploads/` (mentioned in README; not shown in tree but implied) → **File storage** on local disk
- `.env` / `.env.example` (mentioned) → **Configuration** for secrets (GEMINI_API_KEY, PORT)

- **Browser (User)**
- **Frontend page + chat widget**
- **Express server**
- **Upload handling / text extraction**
- **In-memory document store**
- **Uploads folder (disk)**
- **Gemini API**
- **Environment config (.env)**
- **REST endpoints** as the contract boundary

##### Browser UI Container
- `public/index.html` (Bootstrap UI + chat widget)
- Calls REST API endpoints
##### Node.js/Express Container
- `server.js`
- Serves static UI + JSON API
##### Local File Storage
- `uploads/` directory (raw uploaded files)
##### In-Memory Knowledge Store
- Documents array / map in `server.js` (stores extracted text + metadata)
##### External LLM
- Gemini 2.0 Flash API

- Upload flow:
- Browser → `POST /api/upload` → Express
- Express → write file to `uploads/`
- Express → `extractText()` → store extracted text in memory
- Express → response (document id, name, etc.)
- /delete flow:
- Browser → `GET /api/documents` → Express → read from in-memory store → response
- Browser → `DELETE /api/documents/:id` → Express → remove from memory + delete from disk → response
- Chat/RAG flow:
- Browser → `POST /api/chat` (user message)
- Express → build prompt (system instruction + concatenated docs + user question)
- Express → call Gemini API
- Express → return answer → Browser renders in widget

This is where you “separate into as many components as possible” while staying accurate:

**Inside Backend (`server.js`)**
- Static file serving (serves `public/index.html`)
- API Router:
- `/api/health`
- `/api/upload`
- `/api/documents` (GET)
- `/api/documents/:id` (DELETE)
- `/api/chat`
- Upload middleware / multipart handler (e.g., multer-like)
- `extractText()` module/function (noted in README; PDF parsing is currently naïve)
- Document Repository (in-memory array/map):
- stores `{id, filename, extractedText, ...}`
- Disk storage adapter:
- writes/removes actual files in `uploads/`
- Gemini client:
- reads `GEMINI_API_KEY` from env
- sends `model=gemini-2.0-flash` request
- returns generated text

**Inside Frontend (`public/index.html`)**
- Upload UI component (drag/drop + file picker)
- Document list component (renders uploaded docs + delete buttons)
- Chat trigger button (bottom-left bubble)
- API client functions:
- `uploadDocument() -> POST /api/upload`
- `fetchDocuments() -> GET /api/documents`
- `deleteDocument(id) -> DELETE /api/documents/:id`
- `sendChat(message) -> POST /api/chat`

##### Diagramming conventions (so it’s readable and unambiguous)

- “POST upload (multipart)”
- “Store file”
- “Extract text”
- “Build prompt (docs + question)”
- “LLM generate”
- “Return answer (JSON)”

- In-memory store is **not durable**
- PDF parsing is **plain text unless pdf-parse is added**
- RAG is **full-context injection** (no retrieval ranking)

- Don’t imply multi-service microservices; this is a single Node process serving both static UI and API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context
    %% =========================
    subgraph "System Context (C4-1)"
        direction TB

        User["User (Browser)"]:::external

        subgraph "RAG Chatbot Web App (This Project)"
            direction TB
            WebApp["Web App (SPA + Node/Express)"]:::firstparty
        end

        Gemini["Google Gemini API\n(model: gemini-2.0-flash)"]:::externalSvc

        User -->|"Uploads_docs_/_asks_questions_(HTTP)"| WebApp
        WebApp -->|"RAG_prompt=user_question+ALL_docs_context_(HTTPS)"| Gemini
        Gemini -->|"Generated_answer"| WebApp
        WebApp -->|"UI_updates_(HTTP)"| User
    end

    NoteRAG["Note: No_vectorDB/embeddings\nRetrieval=inject_ALL_docs_text_into_prompt"]:::note
    WebApp -.->|"limitation"| NoteRAG

    %% =========================
    %% Container + Key Component Architecture (Combined)
    %% =========================
    subgraph "Container + Key Components (C4-2/3 Combined)"
        direction TB

        %% -------- Browser Boundary --------
        subgraph "Browser Runtime"
            direction TB
            SPA["Single-Page Frontend\n(Upload UI + Document List + Chat Widget)"]:::frontend
            UploadUI["Upload UI\n(file_picker/drag_drop)"]:::frontend
            DocList["Document List UI\n(render IDs + delete buttons)"]:::frontend
            ChatWidget["Chat Widget\n(bottom-left bubble + chat window)"]:::frontend
            ApiClient["API Client Functions\n(upload/fetch/delete/chat)"]:::frontend

            SPA --> UploadUI
            SPA --> DocList
            SPA --> ChatWidget
            SPA --> ApiClient
        end

        %% -------- Server Boundary --------
        subgraph "Server Runtime (Single Node.js Process)"
            direction TB

            Express["Node.js/Express Backend Service"]:::backend

            StaticServe["Static File Serving\n(express.static)"]:::backend
            ApiBoundary["REST API Contract Boundary\n(/api/* routes)"]:::api

            subgraph "API Routes"
                direction TB
                Health["GET /api/health"]:::api
                Upload["POST /api/upload\n(multipart/form-data, <=10MB)"]:::api
                Docs["GET /api/documents\n(JSON list)"]:::api
                Delete["DELETE /api/documents/:id"]:::api
                Chat["POST /api/chat\n(JSON: {message})"]:::api
            end

            UploadHandler["Upload Handling / Multipart Processing"]:::backend
            ExtractText["extractText() / Text Extraction\n(naïve PDF->text per README note)"]:::backend

            InMemStore[("In-Memory Document Store\n{id, filename, extractedText, ...}")]:::mem
            DiskUploads[("Local Disk Storage\nuploads/")]:::storage

            GeminiClient["Gemini API Client + Prompt Builder\n(system_instruction + ALL_docs + user_question)"]:::backend
            EnvCfg["Environment Config\n(.env provides GEMINI_API_KEY, PORT)"]:::config

            Express --> StaticServe
            Express --> ApiBoundary
            ApiBoundary --> Health
            ApiBoundary --> Upload
            ApiBoundary --> Docs
            ApiBoundary --> Delete
            ApiBoundary --> Chat

            Upload -->|"uses"| UploadHandler
            UploadHandler -->|"store_file"| DiskUploads
            UploadHandler -->|"extract_text"| ExtractText
            ExtractText -->|"add_doc_text+metadata"| InMemStore

            Docs -->|"read_docs_metadata"| InMemStore
            Delete -->|"remove_doc_from_memory"| InMemStore
            Delete -->|"delete_file"| DiskUploads

            Chat -->|"build_prompt(docs+question)"| GeminiClient
            GeminiClient -->|"read_key"| EnvCfg
        end

        %% -------- External Boundary --------
        subgraph "External Cloud"
            direction TB
            Gemini2["Google Gemini API\n(gemini-2.0-flash)"]:::externalSvc
        end

        %% -------- Browser <-> Server Flows --------
        ApiClient -->|"POST_/api/upload_(multipart)"| Upload
        ApiClient -->|"GET_/api/documents_(JSON)"| Docs
        ApiClient -->|"DELETE_/api/documents/:id"| Delete
        ApiClient -->|"POST_/api/chat_{message}"| Chat

        Upload -->|"response: {id, filename, ...}"| ApiClient
        Docs -->|"response: [{id, filename, ...}]"| ApiClient
        Delete -->|"response: {ok}"| ApiClient
        Chat -->|"response: {answer}"| ApiClient

        %% -------- Server <-> External LLM --------
        GeminiClient -->|"HTTPS_generate(prompt)"| Gemini2
        Gemini2 -->|"completion_text"| GeminiClient

        %% -------- UI Updates --------
        ApiClient -->|"render_docs"| DocList
        ApiClient -->|"render_chat_answer"| ChatWidget
    end

    %% =========================
    %% Annotations / Callouts
    %% =========================
    NoteDurable["Note: In-memory_store_is_volatile\n(lost_on_server_restart)"]:::note
    InMemStore -.->|"state"| NoteDurable

    NotePDF["Note: PDF_parsing_is_basic/plain\n(add pdf-parse for better extraction)"]:::note
    ExtractText -.->|"quality"| NotePDF

    NoteSecrets["Note: GEMINI_API_KEY_is_server-side\n(not_exposed_to_browser)"]:::note
    EnvCfg -.->|"security"| NoteSecrets

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click SPA "https://github.com/notvishwas/rag-agent/blob/master/public/index.html"
    click StaticServe "https://github.com/notvishwas/rag-agent/tree/master/public/"
    click Express "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click ApiBoundary "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click UploadHandler "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click ExtractText "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click InMemStore "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click GeminiClient "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click EnvCfg "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click ApiClient "https://github.com/notvishwas/rag-agent/blob/master/public/index.html"
    click UploadUI "https://github.com/notvishwas/rag-agent/blob/master/public/index.html"
    click DocList "https://github.com/notvishwas/rag-agent/blob/master/public/index.html"
    click ChatWidget "https://github.com/notvishwas/rag-agent/blob/master/public/index.html"
    click Health "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click Upload "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click Docs "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click Delete "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click Chat "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click WebApp "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click NoteRAG "https://github.com/notvishwas/rag-agent/blob/master/README.md"

    click NotePDF "https://github.com/notvishwas/rag-agent/blob/master/README.md"
    click NoteSecrets "https://github.com/notvishwas/rag-agent/blob/master/README.md"
    click DiskUploads "https://github.com/notvishwas/rag-agent/blob/master/README.md"

    click NoteDurable "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click Gemini2 "https://github.com/notvishwas/rag-agent/blob/master/README.md"
    click Gemini "https://github.com/notvishwas/rag-agent/blob/master/README.md"

    click User "https://github.com/notvishwas/rag-agent/blob/master/public/index.html"
    click EnvCfg "https://github.com/notvishwas/rag-agent/blob/master/.env.example"

    click SPA "https://github.com/notvishwas/rag-agent/blob/master/public/index.html"
    click Express "https://github.com/notvishwas/rag-agent/blob/master/server.js"

    click WebApp "https://github.com/notvishwas/rag-agent/blob/master/package.json"
    click ApiBoundary "https://github.com/notvishwas/rag-agent/blob/master/package.json"
    click Express "https://github.com/notvishwas/rag-agent/blob/master/package.json"

    click NoteRAG "https://github.com/notvishwas/rag-agent/blob/master/package.json"

    click WebApp "https://github.com/notvishwas/rag-agent/blob/master/README.md"
    click Express "https://github.com/notvishwas/rag-agent/blob/master/README.md"

    click WebApp "https://github.com/notvishwas/rag-agent/blob/master/package.json"

    %% Explicit mapping items
    click WebApp "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click Express "https://github.com/notvishwas/rag-agent/blob/master/server.js"
    click SPA "https://github.com/notvishwas/rag-agent/blob/master/public/index.html"
    click StaticServe "https://github.com/notvishwas/rag-agent/tree/master/public/"
    click NoteRAG "https://github.com/notvishwas/rag-agent/blob/master/README.md"
    click WebApp "https://github.com/notvishwas/rag-agent/blob/master/package.json"

    %% =========================
    %% Styles
    %% =========================
    classDef frontend fill:#2f6feb,stroke:#1f4fbf,color:#ffffff,stroke-width:1.5px
    classDef backend fill:#1f8f5f,stroke:#146b45,color:#ffffff,stroke-width:1.5px
    classDef api fill:#0ea5e9,stroke:#0369a1,color:#ffffff,stroke-width:1.5px
    classDef storage fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:1.5px
    classDef mem fill:#64748b,stroke:#334155,color:#ffffff,stroke-width:1.5px
    classDef externalSvc fill:#f59e0b,stroke:#b45309,color:#111827,stroke-width:1.5px
    classDef external fill:#94a3b8,stroke:#475569,color:#0b1220,stroke-width:1.5px
    classDef firstparty fill:#2563eb,stroke:#1d4ed8,color:#ffffff,stroke-width:1.5px
    classDef config fill:#a855f7,stroke:#6b21a8,color:#ffffff,stroke-width:1.5px
    classDef note fill:#fde68a,stroke:#b45309,color:#111827,stroke-width:1px,stroke-dasharray: 4 3
```
