# spkkarri/chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/spkkarri/chatbot
- Repository: https://github.com/spkkarri/chatbot

## Overview

##### Project type and purpose
- This is a full-stack chatbot application (“Chatbot-geminiV3”) that integrates:
- A React frontend (under `src/`)
- A Node.js/Express backend (under `server/`)
- A Python-based Retrieval-Augmented Generation (RAG) microservice (under `server/rag_service/`)
- A vector store (Faiss indices) and a MongoDB database
- Integration with an external LLM (Gemini, via `geminiService.js`)

##### File structure
- Top level: two chatbot versions (V2, V3), a knowledge‐graph (KG) tool, and a Notebook demo—but the main deliverable is V3.
- `Chatbot-geminiV3/src/`: React UI components, styling, API wrapper
- `Chatbot-geminiV3/server/`:
- `routes/`: Express route handlers (auth, chat, upload, syllabus, etc.)
- `models/`: Mongoose schemas for User and ChatHistory
- `middleware/`: JWT authentication
- `services/`: External-LLM wrapper
- `rag_service/`: Python Flask app for document parsing and vector search
- `config/`: DB connection setup
- `faiss_indices/`: persisted Faiss vector indexes
- Configuration & build: `package.json`, `requirements.txt`, `install.sh`

##### Architecture overview
a. Main components (containers):
- Frontend (React SPA)
- Backend API (Node.js/Express)
- RAG Microservice (Python/Flask)
- Vector Store (Faiss indices on disk)
- Database (MongoDB)
- External LLM Provider (Gemini API)
b. Relationships & data flows:
1. User ↔ React SPA
2. SPA → Backend REST endpoints (via `api.js`)
3. Backend:
– Authenticated requests pass through authMiddleware → routes
– Chat route:
- Calls RAG microservice (over HTTP or subprocess) for context vectors
- Calls Gemini LLM via `geminiService.js`
- Persists chat to MongoDB
– File upload route: stores docs, calls RAG’s `file_parser` & `faiss_handler` → updates Faiss indices
4. RAG service → Reads/writes Faiss indices on disk → returns nearest documents
5. Backend ↔ MongoDB for users & chat history
c. Architectural patterns & principles:
- Separation of concerns: UI vs API vs vector search logic
- Microservice for RAG (allows scaling/technology heterogeneity)
- Modular Express routes & middleware
- Persistent vector indices for fast retrieval
d. Key technologies:
- React, React Router, CSS Modules
- Node.js, Express, Mongoose (MongoDB)
- Python, Flask, FAISS, file parsing
- JWT for auth, Axios (or fetch) in frontend, shell scripts for install

##### Detail guidance
- Essential containers:
- React SPA ←→ Node/Express ←→ Python/Flask RAG
- Node/Express ←→ MongoDB
- Python/Flask ←→ Faiss Index files
- Node/Express ←→ External LLM API
- Within each container, show core modules:
- In Backend: “Auth Middleware”, “ChatRoute”, “UploadRoute”, “geminiService”
- In RAG: “file_parser”, “faiss_handler”, “config”
- Persistence: illustrate where files and indices live on disk
- Don’t over-complicate: focus on major moving parts and their interactions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        direction TB
        UI["UI Components"]:::frontend
        APIWrapper["API Wrapper (api.js)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend API (Node.js/Express)"
        direction TB
        Entry["server.js"]:::backend
        MW["Auth Middleware"]:::backend
        subgraph "Routes"
            direction TB
            AuthR["Auth Route"]:::backend
            ChatR["Chat Route"]:::backend
            UploadR["File Upload Route"]:::backend
            FilesR["Static Files Route"]:::backend
            SyllabusR["Syllabus Route"]:::backend
            NetworkR["Network Utilities Route"]:::backend
        end
        subgraph "Models"
            direction TB
            UserM["User Model"]:::backend
            ChatM["ChatHistory Model"]:::backend
        end
        ConfigDB["DB Config"]:::backend
        GeminiS["geminiService"]:::backend
    end

    %% RAG Microservice Layer
    subgraph "RAG Microservice (Python/Flask)"
        direction TB
        App["app.py"]:::rag
        FileP["file_parser.py"]:::rag
        FaissH["faiss_handler.py"]:::rag
        RagConfig["config.py / default.py"]:::rag
        Indexes["Persisted Indices"]:::rag
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MongoDB["MongoDB"]:::datastore
        FaissStore["Faiss Indices on Disk"]:::datastore
        Syllabi["Syllabi Documents"]:::datastore
    end

    %% External Services
    External["External LLM (Gemini API)"]:::external

    %% Connections
    User["User"] --> UI
    UI -->|"HTTP/REST (JSON)"| APIWrapper
    APIWrapper -->|"HTTP/REST"| Entry
    Entry --> MW
    MW --> AuthR
    MW --> ChatR
    MW --> UploadR
    MW --> FilesR
    MW --> SyllabusR
    MW --> NetworkR
    AuthR --> ConfigDB
    ChatR --> FileP
    ChatR --> GeminiS
    ChatR --> MongoDB
    UploadR --> FileP
    FileP --> FaissStore
    FaissH --> FaissStore
    App --> Indexes
    ChatR --> App
    Entry --> ConfigDB
    Entry --> GeminiS
    Entry --> MongoDB
    Entry --> App
    App -->|"reads/writes"| Indexes
    Entry --> External

    %% Click Events
    click UI "https://github.com/spkkarri/chatbot/tree/main/Chatbot-geminiV3/src/components/"
    click APIWrapper "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/src/services/api.js"
    click Entry "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/server.js"
    click AuthR "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/routes/auth.js"
    click ChatR "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/routes/chat.js"
    click UploadR "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/routes/upload.js"
    click FilesR "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/routes/files.js"
    click SyllabusR "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/routes/syllabus.js"
    click NetworkR "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/routes/network.js"
    click MW "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/middleware/authMiddleware.js"
    click UserM "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/models/User.js"
    click ChatM "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/models/ChatHistory.js"
    click ConfigDB "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/config/db.js"
    click GeminiS "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/services/geminiService.js"
    click App "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/rag_service/app.py"
    click FileP "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/rag_service/file_parser.py"
    click FaissH "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/rag_service/faiss_handler.py"
    click RagConfig "https://github.com/spkkarri/chatbot/blob/main/Chatbot-geminiV3/server/rag_service/config.py"
    click Indexes "https://github.com/spkkarri/chatbot/tree/main/Chatbot-geminiV3/server/rag_service/indexes/"
    click FaissStore "https://github.com/spkkarri/chatbot/tree/main/Chatbot-geminiV3/server/faiss_indices/"
    click Syllabi "https://github.com/spkkarri/chatbot/tree/main/Chatbot-geminiV3/server/syllabi/"

    %% Styles
    classDef frontend fill:#CCF,stroke:#333,stroke-width:1px
    classDef backend fill:#CFC,stroke:#333,stroke-width:1px
    classDef rag fill:#FC9,stroke:#333,stroke-width:1px
    classDef datastore fill:#DDD,stroke:#333,stroke-width:1px
    classDef external fill:#DDA,stroke:#333,stroke-width:1px
```
