# bachngoh/aio_data_analyst architecture

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

- Interactive diagram: https://gitdiagram.com/bachngoh/aio_data_analyst
- Repository: https://github.com/bachngoh/aio_data_analyst

## Overview

##### Project type and purpose
- This is a full-stack, AI-powered data analysis application built on Chainlit.
- Purpose: provide an interactive UI for uploading CSV data, running automated analyses (via PandasAI and custom LLM-based agents), generating visualizations, and returning AI-driven insights.

##### File structure
- Top level:
- .chainlit/              → Chainlit configuration and localization
- app.py                  → Entry point tying Chainlit to your app logic
- chainlit.md             → Chainlit interface instructions
- public/                 → Static assets (project logo)
- data/                   → Sample CSVs for training, testing, submission
- src/                    → Core application code
- src breakdown:
- agents/                 → Agent abstractions and concrete LLM-powered agents
– base.py               → Agent interface
– llm_compiler_agent/   → Agent that compiles/generates code via LLM
– pandasai_agent/       → Agent that orchestrates PandasAI for data tasks
- tools/                  → Modular “tools” invoked by agents
– data_analysis/        → Parsers, prompts, execution logic for data analysis
– pandas_tool.py        → Thin wrapper for Pandas operations
- utils/                  → Shared utilities
– llm_utils.py          → LLM request/response handling
– chainlit_response.py  → Formatting responses for Chainlit UI
- const.py                → Constants (e.g., prompt templates, timeouts)

##### README for additional insights
- Key dependencies: Pandas, PandasAI, LlamaIndex (RAG), Chainlit (UI layer)
- Features: automated analysis, interactive visualizations, AI recommendations
- Launch command: `chainlit run app.py` (implies a frontend served by Chainlit, backend logic in app.py invoking src modules)

a. Main components
- User & Browser (web UI)
- Chainlit Server / Frontend Layer
- Application Core (app.py)
- Agent Manager (src/agents/base.py orchestrator)
- Specific Agents
– LLM Compiler Agent (code generation, advanced prompts)
– PandasAI Agent (data manipulation, visualizations)
- Tools Layer (src/tools)
– Data Analysis Tool (output parser, prompts)
– Pandas Tool (wrapper for data ops)
- Data Store (local CSV files)
- External Services
– LLM Provider (OpenAI, etc.)
– LlamaIndex (for vector retrieval/RAG)
b. Relationships & interactions
1. User interacts with Chainlit UI
2. Chainlit forwards requests to app.py
3. app.py invokes the Agent Manager
4. Agent Manager dispatches to the correct Agent
5. Agent calls Tools or LLM via llm_utils & LlamaIndex
6. Results are formatted by chainlit_response and sent back to the UI
7. CSV data can be read/written from the data folder via Pandas Tool
c. Architectural patterns & principles
- Modular “agent” pattern: each agent has a single responsibility
- Tool abstraction: decouples business logic from LLM prompts and parsing
- Clear separation: UI (Chainlit) ↔ Orchestration (app.py + Agent Manager) ↔ Execution (Agents/Tools)
d. Key technologies to call out
- Chainlit (UI framework)
- Pandas & PandasAI (data operations)
- LLM Provider & LlamaIndex (RAG retrieval)
- Python modules (src/agents, src/tools, src/utils)

## Diagram (Mermaid)

```mermaid
graph TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        User["User & Browser"]:::frontend
        ChainlitUI["Chainlit Server/UI"]:::frontend
        Config[".chainlit/config.toml"]:::frontend
        Translations[".chainlit/translations/en-US.json"]:::frontend
        Instructions["chainlit.md"]:::frontend
    end

    %% Application Core
    subgraph "Application Core"
        direction TB
        App["app.py"]:::core
        AgentMgr["Agent Manager\n(src/agents/base.py)"]:::core
    end

    %% Agents
    subgraph "Agents"
        direction TB
        LLMCompilerAgent["LLM Compiler Agent\n(agent.py)"]:::agent
        LLMCompilerPrompts["LLM Compiler Prompts\n(prompts.py)"]:::agent
        PandasAIAgent["PandasAI Agent\n(agent.py)"]:::agent
    end

    %% Tools
    subgraph "Tools Layer"
        direction TB
        DataAnalysisTool["Data Analysis Tool\n(tool.py)"]:::tool
        DataAnalysisPrompts["Data Analysis Prompts\n(prompts.py)"]:::tool
        OutputParser["Output Parser\n(output_parser.py)"]:::tool
        PandasTool["Pandas Tool\n(pandas_tool.py)"]:::tool
    end

    %% Utilities & Constants
    subgraph "Utils & Config"
        direction TB
        LLMUtils["llm_utils.py"]:::util
        ChainlitResp["chainlit_response.py"]:::util
        Const["const.py"]:::util
    end

    %% Data Store
    DataStore["CSV Data Store"]:::data
    subgraph "Data Files"
        train["train.csv"]:::data
        test["test.csv"]:::data
        solution["solution.csv"]:::data
        sampleSub["sample_submission.csv"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMProvider["LLM Provider"]:::external
        RAG["LlamaIndex (RAG)"]:::external
    end

    %% Flows
    User -->|interacts with| ChainlitUI
    ChainlitUI -->|requests| App
    App -->|dispatches| AgentMgr
    AgentMgr -->|uses| LLMCompilerAgent
    AgentMgr -->|uses| PandasAIAgent
    LLMCompilerAgent -->|loads prompts| LLMCompilerPrompts
    LLMCompilerAgent -->|calls| LLMProvider
    PandasAIAgent -->|uses| DataAnalysisTool
    PandasAIAgent -->|uses| PandasTool
    DataAnalysisTool -->|loads prompts| DataAnalysisPrompts
    DataAnalysisTool -->|parses output| OutputParser
    PandasTool -->|reads/writes| DataStore
    DataStore --> train
    DataStore --> test
    DataStore --> solution
    DataStore --> sampleSub
    PandasAIAgent -->|calls| LLMProvider
    PandasAIAgent -->|retrieves| RAG
    LLMProvider -->|responses| LLMUtils
    RAG -->|documents| LLMUtils
    LLMUtils -->|formats| ChainlitResp
    ChainlitResp -->|sends| ChainlitUI

    %% Click Events
    click Config "https://github.com/bachngoh/aio_data_analyst/blob/main/.chainlit/config.toml"
    click Translations "https://github.com/bachngoh/aio_data_analyst/blob/main/.chainlit/translations/en-US.json"
    click Instructions "https://github.com/bachngoh/aio_data_analyst/blob/main/chainlit.md"
    click App "https://github.com/bachngoh/aio_data_analyst/blob/main/app.py"
    click AgentMgr "https://github.com/bachngoh/aio_data_analyst/blob/main/src/agents/base.py"
    click LLMCompilerAgent "https://github.com/bachngoh/aio_data_analyst/blob/main/src/agents/llm_compiler_agent/agent.py"
    click LLMCompilerPrompts "https://github.com/bachngoh/aio_data_analyst/blob/main/src/agents/llm_compiler_agent/prompts.py"
    click PandasAIAgent "https://github.com/bachngoh/aio_data_analyst/blob/main/src/agents/pandasai_agent/agent.py"
    click DataAnalysisTool "https://github.com/bachngoh/aio_data_analyst/blob/main/src/tools/data_analysis/tool.py"
    click DataAnalysisPrompts "https://github.com/bachngoh/aio_data_analyst/blob/main/src/tools/data_analysis/prompts.py"
    click OutputParser "https://github.com/bachngoh/aio_data_analyst/blob/main/src/tools/data_analysis/output_parser.py"
    click PandasTool "https://github.com/bachngoh/aio_data_analyst/blob/main/src/tools/pandas_tool.py"
    click LLMUtils "https://github.com/bachngoh/aio_data_analyst/blob/main/src/utils/llm_utils.py"
    click ChainlitResp "https://github.com/bachngoh/aio_data_analyst/blob/main/src/utils/chainlit_response.py"
    click Const "https://github.com/bachngoh/aio_data_analyst/blob/main/src/const.py"
    click train "https://github.com/bachngoh/aio_data_analyst/blob/main/data/train.csv"
    click test "https://github.com/bachngoh/aio_data_analyst/blob/main/data/test.csv"
    click solution "https://github.com/bachngoh/aio_data_analyst/blob/main/data/solution.csv"
    click sampleSub "https://github.com/bachngoh/aio_data_analyst/blob/main/data/sample_submission.csv"
    click DataStore "https://github.com/bachngoh/aio_data_analyst/tree/main/data"
    click public "https://github.com/bachngoh/aio_data_analyst/tree/main/public/"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#3A78FF,color:#003366;
    classDef core fill:#DFFFE0,stroke:#33AA00,color:#005500;
    classDef agent fill:#FFEFD6,stroke:#FF8C00,color:#663300;
    classDef tool fill:#E8E8E8,stroke:#707070,color:#303030;
    classDef util fill:#F0E0FF,stroke:#A020F0,color:#4B0082;
    classDef data fill:#F5F5F5,stroke:#808080,color:#404040;
    classDef external fill:#FFF2CC,stroke:#E69138,color:#974B00;
```
