# jayandhan03/data-analyst-agent architecture

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

- Interactive diagram: https://gitdiagram.com/jayandhan03/data-analyst-agent
- Repository: https://github.com/jayandhan03/data-analyst-agent

## Overview

##### Project Type and Purpose
- This is a full-stack, multi-agent AI system (“Data Analyst Agent”) that automates end-to-end BI workflows.
- It orchestrates a series of AI sub-agents (preprocessor planner, cleaner, reporter, visualizer) under a Supervisor Agent, powered by LangGraph, LangChain Agents, and Gemini API, with a Streamlit UI.

##### File Structure Analysis
- Top-level agent scripts: Cleaner_Agent.py, Report_agent.py, Visualizer_agent.py, Report_agent.py
- Core orchestrator and entrypoints: app.py (Streamlit UI), main.py, llm.py
- Toolkit and guardrails: Toolkit/Tools.py, Guardrails/*.py
- Experiment folder: Jupyter notebooks and standalone scripts (scraper, database, run), illustrating data pipelines and proof-of-concepts
- Devops: Dockerfile, .dockerignore, GitHub Actions workflow for deploying to Streamlit Cloud
- Config & orchestration: Prompts.py, requirements.txt

##### Insights from README
- Supervisor Agent routes tasks, maintains memory
- Sub-agents: Planner → Cleaner → Reporter → Visualizer
- Orchestration: LangGraph
- Memory & chains: LangChain
- LLM provider: Gemini API
- UI layer: Streamlit (app.py)
- Deployment: Streamlit Cloud via Docker/GitHub Actions

a. Main Components
- Frontend UI (Streamlit app.py)
- Supervisor Agent (main orchestration layer)
- Preprocessor Planner Agent module
- Cleaner Agent module
- Report Agent module
- Visualizer Agent module
- Language Model API (Gemini)
- Memory store (LangChain memory)
- Toolkit & Guardrails (Tools.py and guardrails modules)
- Data storage (CSV/Excel input, ephemeral in-memory)
- Deployment infra (Docker container, GitHub Actions)

b. Relationships and Data Flows
- User uploads dataset via UI → Streamlit frontend
- UI sends user intent + data to Supervisor Agent
- Supervisor consults Prompts.py & memory store → decides next agent
- Planner Agent returns a preprocessing plan → passed back to Supervisor
- Supervisor invokes Cleaner Agent with plan → validation feedback loops via Guardrails
- Cleaned data forwarded to Report Agent → insights & story generated
- Insights fed to Visualizer Agent → plots returned
- Supervisor aggregates outputs → UI renders report + visuals
- All LLM calls route through llm.py → Gemini API

c. Architectural Patterns & Principles
- Modular, pipeline-based agent microservices
- Orchestration with a central Supervisor Agent (controller)
- Separation of concerns: planning, cleaning, analyzing, visualizing
- Guardrails as an orthogonal cross-cutting concern for quality and validation
- Memory-driven reasoning: shared state across multi-turn interactions

d. Key Technologies & Frameworks
- Orchestration: LangGraph
- Agent framework & memory: LangChain Agents
- LLM provider: Gemini API
- UI: Streamlit (app.py)
- Containerization: Dockerfile
- CI/CD: GitHub Actions workflow (deploy-to-hf-space.yml)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Docker Container"
        UI["Streamlit UI\n(app.py)"]:::ui
        Supervisor["Supervisor Agent\n(main.py)"]:::orchestrator
        Planner["Preprocessor Planner Agent\n(Prompts.py)"]:::agent
        Cleaner["Cleaner Agent\n(Cleaner_Agent.py)"]:::agent
        Reporter["Report Agent\n(Report_agent.py)"]:::agent
        Visualizer["Visualizer Agent\n(Visualizer_agent.py)"]:::agent
        Toolkit["Toolkit\n(Toolkit/Tools.py)"]:::crosscut
        Guardrails["Guardrails\n(Guardrails/)"]:::crosscut
        Memory["Memory Store\n(LangChain)"]:::data
        DataIn["CSV/Excel Input"]:::data
        LLM["Gemini API\n(via llm.py)"]:::external
        DockerCfg["Dockerfile"]:::devops
        UI -->|uploads data| Supervisor
        DataIn -->|provides data| UI
        Supervisor -->|routes task| Planner
        Planner -->|returns plan| Supervisor
        Supervisor -->|invokes| Cleaner
        Cleaner -->|validates| Supervisor
        Supervisor -->|sends cleaned data| Reporter
        Reporter -->|sends insights| Supervisor
        Supervisor -->|sends insights| Visualizer
        Visualizer -->|returns visuals| Supervisor
        Supervisor -->|renders output| UI
        Planner -->|calls LLM| LLM
        Cleaner -->|calls LLM| LLM
        Reporter -->|calls LLM| LLM
        Visualizer -->|calls LLM| LLM
        Supervisor -->|reads/writes| Memory
        Planner -->|reads/writes| Memory
        Cleaner -->|reads/writes| Memory
        Reporter -->|reads/writes| Memory
        Visualizer -->|reads/writes| Memory
        Planner -->|uses| Guardrails
        Cleaner -->|uses| Guardrails
        Planner -->|uses| Toolkit
        Cleaner -->|uses| Toolkit
        Reporter -->|uses| Toolkit
        Visualizer -->|uses| Toolkit
    end

    Experiments["Experiments\n(Experiments/)"]:::ci
    CI["GitHub Actions\n(deploy-to-hf-space.yml)"]:::ci

    Experiments -->|proofs-of-concept| DockerCfg
    CI -->|deploys container| DockerCfg

    click UI "https://github.com/jayandhan03/data-analyst-agent/blob/master/app.py"
    click Supervisor "https://github.com/jayandhan03/data-analyst-agent/blob/master/main.py"
    click Planner "https://github.com/jayandhan03/data-analyst-agent/blob/master/Prompts.py"
    click Cleaner "https://github.com/jayandhan03/data-analyst-agent/blob/master/Cleaner_Agent.py"
    click Reporter "https://github.com/jayandhan03/data-analyst-agent/blob/master/Report_agent.py"
    click Visualizer "https://github.com/jayandhan03/data-analyst-agent/blob/master/Visualizer_agent.py"
    click LLM "https://github.com/jayandhan03/data-analyst-agent/blob/master/llm.py"
    click Toolkit "https://github.com/jayandhan03/data-analyst-agent/blob/master/Toolkit/Tools.py"
    click Guardrails "https://github.com/jayandhan03/data-analyst-agent/tree/master/Guardrails/"
    click DockerCfg "https://github.com/jayandhan03/data-analyst-agent/tree/master/Dockerfile"
    click CI "https://github.com/jayandhan03/data-analyst-agent/blob/master/.github/workflows/deploy-to-hf-space.yml"
    click Experiments "https://github.com/jayandhan03/data-analyst-agent/tree/master/Experiments/"

    classDef ui fill:#ADD8E6,stroke:#000;
    classDef orchestrator fill:#90EE90,stroke:#000;
    classDef agent fill:#FFA500,stroke:#000;
    classDef external fill:#DDA0DD,stroke:#000;
    classDef data fill:#E0FFFF,stroke:#000;
    classDef crosscut fill:#FFD700,stroke:#000;
    classDef devops fill:#D3D3D3,stroke:#000;
    classDef ci fill:#D3D3D3,stroke:#000;
```
