# amanr24/databot architecture

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

- Interactive diagram: https://gitdiagram.com/amanr24/databot
- Repository: https://github.com/amanr24/databot

## Overview

##### Project type and purpose
- DATAbot is a full-stack, single-process Streamlit application that exposes a chat interface (“Chatbot Mode”) and a separate “Dashboard Mode.”
- It implements a multi-agent orchestration layer to handle EDA, visualization, SQL query generation, PDF question-answering, voice I/O, and an AutoML/forecasting dashboard.

##### File structure
Top‐level directories/files:
- src/app.py – the Streamlit entrypoint (the “frontend”)
- src/multiagent_router.py – the core dispatcher that receives user requests and routes them to one of several agents
- src/agents/… – three agent classes:
- eda_database_agent.py (EDA narrative & chart agent)
- sql_database_agent.py (SQL generation & execution agent)
- pdf_database_agent.py (RAG-over-PDF agent)
- src/tools/… – low-level utilities and wrappers (Sweetviz/Plotly/Matplotlib/Seaborn, SQLAlchemy, Whisper STT, browser TTS, Python code runner, dashboard integration)
- requiements.txt – Python dependencies including Streamlit, LangChain, Groq SDK, PyCaret, Prophet, Sweetviz, Whisper, etc.
- images/ & videos/ – static assets for documentation

##### Key insights from README
- Streamlit UI for two modes: Chatbot & Dashboard
- SQLite for persisting uploaded CSVs
- LangChain + Groq’s LLM as the “brain” behind all agents
- Five major tool-based capabilities: EDA summaries, chart generation, SQL, PDF RAG, voice I/O
- Dashboard mode uses PyCaret (AutoML), What-If simulation, Prophet (time-series), plus data-cleaning utilities

##### Main components
a. Frontend/UI
- Streamlit App (src/app.py)
- Mode toggle (Chatbot vs. Dashboard)
b. Orchestration Layer
- MultiAgent Router (src/multiagent_router.py)
c. Agents
- EDA Agent
- SQL Agent
- PDF Agent
d. Tools / Worker Modules
- EDA & Visualization (eda.py + Sweetviz + Plotly/Matplotlib/Seaborn)
- SQL utilities (sql.py + SQLAlchemy)
- DataFrame helpers (dataframe.py)
- Python code execution (python_run.py)
- Voice translation (voice_translator.py + Whisper)
- TTS rendering (tts_renderer.py)
- Dashboard integration (dashboard.py + PyCaret + Prophet)
e. Persistence & Storage
- SQLite database (local file) for CSV ingestion
- Filesystem storage for uploaded PDFs & generated reports
f. External Services
- Groq LLM API (via LangChain)
- Optional browser audio APIs for TTS playback

##### Relationships and data flows
- Streamlit UI → (user request) → MultiAgent Router
- Router → selects an Agent based on request type
- Agent → calls one or more Tools
- Tools → interact with Database / File System / External LLM API
- Agent → returns processed results (text, charts, SQL results, audio data) → Router → UI
- Dashboard tools bypass the router and feed directly into dashboard.py components

##### Architectural patterns & design principles
- Multi-agent orchestration (plugin-style agents extend a common interface)
- Tool abstraction for external calls (separation of concerns between agent logic and low-level operations)
- Monolithic service but modularized into layers (UI → Router → Agents → Tools → Persistence/External)
- Event-driven flow with directional data streams

##### Technologies & frameworks to annotate
- Streamlit (UI layer)
- LangChain + Groq SDK (LLM orchestration)
- SQLAlchemy + SQLite (data persistence)
- Sweetviz, Plotly, Matplotlib, Seaborn (visualization)
- PyCaret, Prophet (dashboard analytics)
- Whisper (STT) + browser TTS (voice I/O)
- Python subprocess or eval (python_run tool)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: UI
    subgraph "Frontend/UI"
        direction TB
        StreamlitApp["Streamlit App"]:::frontend
        ModeToggle["Mode Toggle\n(Chatbot vs Dashboard)"]:::frontend
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Router["MultiAgent Router"]:::orchestration
    end

    %% Agents Layer
    subgraph "Agents"
        direction TB
        EDAAgent["EDA Agent"]:::agent
        SQLAgent["SQL Agent"]:::agent
        PDFAgent["PDF Agent"]:::agent
    end

    %% Tools Layer
    subgraph "Tools & Helpers"
        direction TB
        EDAVisTool["EDA & Visualization Tools"]:::tools
        SQLUtils["SQL Utilities"]:::tools
        DFHelpers["DataFrame Helpers"]:::tools
        PythonRun["Python Code Execution Tool"]:::tools
        VoiceTranslator["Voice Translation Tool"]:::tools
        TTSRenderer["TTS Rendering Tool"]:::tools
        DashboardTool["Dashboard Integration"]:::tools
    end

    %% Persistence & Storage
    subgraph "Persistence & Storage"
        direction TB
        SQLiteDB["SQLite Database"]:::storage
        FileSystem["File System Storage"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GroqAPI["Groq LLM API"]:::external
        BrowserAudio["Browser Audio API"]:::external
    end

    %% Connections
    User -->|interacts| StreamlitApp
    StreamlitApp -->|toggles mode| ModeToggle
    ModeToggle -->|user request| Router

    Router -->|EDA request| EDAAgent
    Router -->|SQL request| SQLAgent
    Router -->|PDF request| PDFAgent

    EDAAgent -->|visualization/EDA| EDAVisTool
    SQLAgent -->|generate SQL| SQLUtils
    SQLAgent -->|data ops| DFHelpers
    PDFAgent -->|PDF processing| FileSystem

    EDAVisTool -->|load CSV| SQLiteDB
    SQLUtils -->|query DB| SQLiteDB
    DashboardTool -->|data analytics| SQLiteDB

    EDAAgent -->|LLM prompt/response| GroqAPI
    SQLAgent -->|LLM prompt/response| GroqAPI
    PDFAgent -->|LLM prompt/response| GroqAPI

    StreamlitApp -->|dashboard mode| DashboardTool
    DashboardTool -->|AutoML/Forecast| DashboardTool

    Router -->|voice input| VoiceTranslator
    Router -->|audio output| TTSRenderer
    VoiceTranslator -->|transcript| Router
    TTSRenderer -->|audio| BrowserAudio

    %% Return flows
    EDAAgent -->|results| Router
    SQLAgent -->|results| Router
    PDFAgent -->|results| Router
    DashboardTool -->|dashboard data| StreamlitApp

    Router -->|response| StreamlitApp

    %% Click Events
    click StreamlitApp "https://github.com/amanr24/databot/blob/main/src/app.py"
    click ModeToggle "https://github.com/amanr24/databot/blob/main/src/app.py"
    click Router "https://github.com/amanr24/databot/blob/main/src/multiagent_router.py"
    click EDAAgent "https://github.com/amanr24/databot/blob/main/src/agents/eda_database_agent.py"
    click SQLAgent "https://github.com/amanr24/databot/blob/main/src/agents/sql_database_agent.py"
    click PDFAgent "https://github.com/amanr24/databot/blob/main/src/agents/pdf_database_agent.py"
    click EDAVisTool "https://github.com/amanr24/databot/blob/main/src/tools/eda.py"
    click SQLUtils "https://github.com/amanr24/databot/blob/main/src/tools/sql.py"
    click DFHelpers "https://github.com/amanr24/databot/blob/main/src/tools/dataframe.py"
    click PythonRun "https://github.com/amanr24/databot/blob/main/src/tools/python_run.py"
    click VoiceTranslator "https://github.com/amanr24/databot/blob/main/src/tools/voice_translator.py"
    click TTSRenderer "https://github.com/amanr24/databot/blob/main/src/tools/tts_renderer.py"
    click DashboardTool "https://github.com/amanr24/databot/blob/main/src/tools/dashboard.py"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#007ACC,color:#000
    classDef orchestration fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef agent fill:#A5D6A7,stroke:#2E7D32,color:#000
    classDef tools fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef storage fill:#E0E0E0,stroke:#757575,color:#000
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#000
```
