# sharadgup/ai-research-assistant-system architecture

> Architecture diagram of the GitHub repository sharadgup/ai-research-assistant-system, 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/sharadgup/ai-research-assistant-system
- Repository: https://github.com/sharadgup/ai-research-assistant-system

## Overview

##### Main System Components
a. Client (Web Browser)
- Static assets: HTML templates (Jinja2), CSS, JavaScript
- Pages: Landing, Login/Register, Dashboard, Domain‑agent interfaces (Education, Healthcare, Construction, News, PDF Analyzer, Data Analyzer, Data Cleaner, Voice Agent)
- Socket.IO client for real‑time chat and voice events
b. Backend Application
- Entry point: `app.py` (Flask app, Flask‑SocketIO, Eventlet)
- Blueprints / Routes:
- Auth routes (`auth_routes.py`)
- Chat & PDF chat routes (`chat_routes.py`, `pdf_routes.py`)
- Report routes (`report_routes.py`)
- Socket handlers: `voice_handlers.py`, `pdf_chat_handlers.py`
- Utilities: `pdf_utils.py`, `chart_parser.py`, `voice_utils.py`
- Models: `user_model.py`, `report_model.py`
- Configuration loader (`config.py`)
c. Data & File Storage
- MongoDB (user sessions, metadata, transcripts)
- File system: `uploads/` (PDFs), `uploads/analysis_data/` (CSV exports)
d. External Services
- Google Generative AI (Gemini) for text semantics, chat, TTS
- Google OAuth 2.0 (via Flask‑Dance)

##### Component Relationships & Data Flows
- Web Browser → HTTP/HTTPS → Flask Routes (Auth, Chat, PDF, Report)
- Web Browser ↔ WebSocket → Socket Handlers (real‑time chat & voice)
- Flask Application → MongoDB → CRUD for users, reports, transcripts
- Flask Utilities → File System → PDF ingestion & storage
- Flask Utilities → Google Gemini API → AI processing (analysis, chat responses, TTS audio)
- Chart Parser Utility → Generates chart data → Frontend charts via JSON over HTTP

##### Architectural Patterns & Principles
- Layered architecture:
- Presentation (templates + static JS/CSS)
- Application logic (Flask routes + SocketIO handlers)
- Domain logic (utils + models)
- Infrastructure (MongoDB, file storage, external AI service)
- MVC‑style separation via Flask Blueprints and Jinja2 templates
- Event‑driven real‑time interactions using WebSockets (Flask‑SocketIO + Eventlet)
- Asynchronous, non‑blocking I/O for low‑latency voice & chat
- Extensible “multi‑agent” pattern: each domain agent (education, healthcare, construction, news, PDF, data) implemented as distinct route + template + JS module

##### Technologies & Frameworks
- Backend: Python, Flask, Flask‑SocketIO, Eventlet, Flask‑Dance, PyMuPDF (fitz)
- AI Engine: google‑generativeai (Gemini 1.5 Flash)
- Database: MongoDB
- Frontend: HTML/CSS, vanilla JS (Fetch API), Socket.IO client
- Deployment helpers: devserver.sh, Procfile (Heroku), Nix (`dev.nix`)

##### Final Checklist
[ ] Detailed path of a representative flow (e.g., PDF → chat → AI → response)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        Browser["Web Browser"]:::frontend
        StaticAssets["Client Static Assets<br>(HTML/CSS/JS)"]:::frontend
        Templates["Client Templates<br>(Jinja2 Pages)"]:::frontend
        SocketClient["Socket.IO Client"]:::frontend
    end

    subgraph "Backend: Flask Application"
        App["app.py<br>(Flask Init, Blueprints, SocketIO)"]:::backend
        Config["Config Loader<br>(config.py)"]:::backend
        AuthRoutes["Auth Blueprint<br>(auth_routes.py)"]:::backend
        ChatRoutes["Chat & PDF Blueprints<br>(chat_routes.py, pdf_routes.py)"]:::backend
        ReportRoutes["Report Blueprint<br>(report_routes.py)"]:::backend
        VoiceHandlers["Voice Handlers<br>(voice_handlers.py)"]:::backend
        PDFChatHandlers["PDF Chat Handlers<br>(pdf_chat_handlers.py)"]:::backend
        Utils["Utilities<br>(pdf_utils.py, chart_parser.py, voice_utils.py)"]:::backend
        Models["Models<br>(user_model.py, report_model.py)"]:::backend
        Requirements["requirements.txt"]:::backend
        ProcfileNode["Procfile"]:::backend
        DevServerNode["devserver.sh"]:::backend
        NixNode[".idx/dev.nix"]:::backend
    end

    subgraph "Storage & External Services"
        Mongo["MongoDB"]:::storage
        UploadsNode["Uploaded PDFs<br>(uploads/)"]:::storage
        AnalysisData["Analysis Data<br>(uploads/analysis_data/)"]:::storage
        Gemini["Google Gemini API"]:::external
        OAuth["Google OAuth 2.0"]:::external
    end

    Browser -->|HTTP/HTTPS| App
    Browser --> SocketClient
    SocketClient -->|Socket.IO| App

    App --> AuthRoutes
    App --> ChatRoutes
    App --> ReportRoutes
    App --> VoiceHandlers
    App --> PDFChatHandlers
    App --> Config

    AuthRoutes --> Models
    AuthRoutes --> OAuth

    ChatRoutes --> Models
    ChatRoutes --> Utils
    ChatRoutes --> Gemini

    PDFChatHandlers --> Utils
    PDFChatHandlers --> Gemini

    VoiceHandlers --> Utils
    VoiceHandlers --> Gemini

    Models --> Mongo

    Utils --> UploadsNode
    UploadsNode --> Utils
    Utils --> AnalysisData
    Utils --> Mongo
    Utils --> Gemini

    click StaticAssets "https://github.com/sharadgup/ai-research-assistant-system/tree/main/src/static/"
    click Templates "https://github.com/sharadgup/ai-research-assistant-system/tree/main/src/templates/"
    click App "https://github.com/sharadgup/ai-research-assistant-system/blob/main/app.py"
    click Requirements "https://github.com/sharadgup/ai-research-assistant-system/blob/main/requirements.txt"
    click ProcfileNode "https://github.com/sharadgup/ai-research-assistant-system/tree/main/Procfile"
    click DevServerNode "https://github.com/sharadgup/ai-research-assistant-system/blob/main/devserver.sh"
    click NixNode "https://github.com/sharadgup/ai-research-assistant-system/blob/main/.idx/dev.nix"
    click UploadsNode "https://github.com/sharadgup/ai-research-assistant-system/tree/main/uploads/"
    click AnalysisData "https://github.com/sharadgup/ai-research-assistant-system/tree/main/uploads/analysis_data/"

    classDef frontend fill:#cce5ff,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
```
