# sneha-nayak546/agentic-analyst architecture

> Architecture diagram of the GitHub repository sneha-nayak546/agentic-analyst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sneha-nayak546/agentic-analyst
- Repository: https://github.com/sneha-nayak546/agentic-analyst

## Overview

Agentic Analyst turns business questions into read-only analytics, then presents results in a React interface. The documented workflow routes intent, enriches context with schema and business knowledge, synthesizes SQL through deterministic or LLM paths, validates it, and executes against the database. Other documented modes provide tutoring, ERDs, dashboards, and narratives. Source excerpts are partial, so links for documented but unsampled internals follow the README architecture; uncertain implementation details are omitted.

Main entry points: [`app/agent/sql_agent.py`](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/sql_agent.py) (SQL Agent), [`frontend/src/App.jsx`](https://github.com/sneha-nayak546/agentic-analyst/blob/main/frontend/src/App.jsx) (React App), [`app/agent/intent_router.py`](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/intent_router.py) (Intent Router), [`app/api/main.py`](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/api/main.py) (FastAPI Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["React App<br/>[App.jsx]"]
  node_chat["Collaborator Chat<br/>[CenterChat.jsx]"]
  node_visuals["Results and Charts<br/>[AutoChart.jsx]"]
  node_dashboards["Dashboard Views<br/>[DashboardPage.jsx]"]
  node_reports["Reports and Export<br/>[export_router.py]"]
end

subgraph group_orchestration["Agent Orchestration"]
  node_api["FastAPI Gateway<br/>[main.py]"]
  node_agent["SQL Agent<br/>[sql_agent.py]"]
  node_intent["Intent Router<br/>[intent_router.py]"]
  node_planner["Query Planner<br/>[query_planner.py]"]
  node_memory[("Session Memory<br/>[memory_manager.py]")]
  node_personas["Analyst Personas<br/>[collaborator.py]"]
end

subgraph group_knowledge["Knowledge Context"]
  node_knowledge["Knowledge Graph<br/>[knowledge_graph.py]"]
  node_retriever["Schema Retriever<br/>[retriever.py]"]
  node_vectors[("ChromaDB<br/>[retriever.py]")]
end

subgraph group_query["SQL Governance"]
  node_synth["SQL Synthesizer<br/>[sql_generator.py]"]
  node_llm["Ollama Qwen<br/>[qwen.py]"]
  node_validator["SQL Validator<br/>[query_validator.py]"]
end

subgraph group_data["Data and Persistence"]
  node_executor["Read Executor<br/>[read_executor.py]"]
  node_mysql[("MySQL Database")]
  node_history[("Query History<br/>[query_history.py]")]
end

node_user(("Analyst"))

node_user -->|"asks"| node_web
node_web -->|"shows chat"| node_chat
node_chat -->|"sends question"| node_api
node_api -->|"calls"| node_agent
node_agent -->|"routes intent"| node_intent
node_intent -->|"resolves context"| node_memory
node_intent -->|"dispatches modes"| node_personas
node_intent -->|"plans analytics"| node_planner
node_planner -->|"resolves entities"| node_knowledge
node_agent -->|"retrieves context"| node_retriever
node_retriever -->|"queries embeddings"| node_vectors
node_agent -->|"generates routine SQL"| node_synth
node_agent -->|"generates complex SQL"| node_llm
node_agent -->|"validates SQL"| node_validator
node_validator -->|"approves read query"| node_executor
node_executor -->|"executes read"| node_mysql
node_executor -->|"returns rows"| node_agent
node_agent -->|"returns results"| node_visuals
node_web -->|"opens views"| node_dashboards
node_web -->|"requests exports"| node_reports
node_api -->|"logs queries"| node_history
node_agent -.->|"enriches successful queries"| node_knowledge

click node_web "https://github.com/sneha-nayak546/agentic-analyst/blob/main/frontend/src/App.jsx"
click node_chat "https://github.com/sneha-nayak546/agentic-analyst/blob/main/frontend/src/components/CenterChat.jsx"
click node_visuals "https://github.com/sneha-nayak546/agentic-analyst/blob/main/frontend/src/components/AutoChart.jsx"
click node_dashboards "https://github.com/sneha-nayak546/agentic-analyst/blob/main/frontend/src/components/DashboardPage.jsx"
click node_reports "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/api/export_router.py"
click node_api "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/api/main.py"
click node_agent "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/sql_agent.py"
click node_intent "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/intent_router.py"
click node_planner "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/query_planner.py"
click node_memory "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/memory_manager.py"
click node_personas "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/collaborator.py"
click node_knowledge "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/knowledge/knowledge_graph.py"
click node_retriever "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/retriever/retriever.py"
click node_vectors "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/chroma/retriever.py"
click node_synth "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/llm/sql_generator.py"
click node_llm "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/llm/qwen.py"
click node_validator "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/validator/query_validator.py"
click node_executor "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/database/read_executor.py"
click node_history "https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/sql_history/query_history.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_chat,node_visuals,node_dashboards,node_reports toneBlue
class node_api,node_agent,node_intent,node_planner,node_memory,node_personas toneAmber
class node_knowledge,node_retriever,node_vectors toneMint
class node_synth,node_llm,node_validator toneRose
class node_executor,node_mysql,node_history,node_user toneIndigo
```

## Components

### User Experience

- [React App](https://github.com/sneha-nayak546/agentic-analyst/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Collaborator Chat](https://github.com/sneha-nayak546/agentic-analyst/blob/main/frontend/src/components/CenterChat.jsx): `frontend/src/components/CenterChat.jsx`
- [Results and Charts](https://github.com/sneha-nayak546/agentic-analyst/blob/main/frontend/src/components/AutoChart.jsx): `frontend/src/components/AutoChart.jsx`
- [Dashboard Views](https://github.com/sneha-nayak546/agentic-analyst/blob/main/frontend/src/components/DashboardPage.jsx): `frontend/src/components/DashboardPage.jsx`
- [Reports and Export](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/api/export_router.py): `app/api/export_router.py`

### Agent Orchestration

- [FastAPI Gateway](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/api/main.py): `app/api/main.py`
- [SQL Agent](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/sql_agent.py): `app/agent/sql_agent.py`
- [Intent Router](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/intent_router.py): `app/agent/intent_router.py`
- [Query Planner](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/query_planner.py): `app/agent/query_planner.py`
- [Session Memory](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/memory_manager.py): `app/agent/memory_manager.py`
- [Analyst Personas](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/agent/collaborator.py): `app/agent/collaborator.py`

### Knowledge Context

- [Knowledge Graph](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/knowledge/knowledge_graph.py): `app/knowledge/knowledge_graph.py`
- [Schema Retriever](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/retriever/retriever.py): `app/retriever/retriever.py`
- [ChromaDB](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/chroma/retriever.py): `app/chroma/retriever.py`

### SQL Governance

- [SQL Synthesizer](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/llm/sql_generator.py): `app/llm/sql_generator.py`
- [Ollama Qwen](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/llm/qwen.py): `app/llm/qwen.py`
- [SQL Validator](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/validator/query_validator.py): `app/validator/query_validator.py`

### Data and Persistence

- [Read Executor](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/database/read_executor.py): `app/database/read_executor.py`
- **MySQL Database**
- [Query History](https://github.com/sneha-nayak546/agentic-analyst/blob/main/app/sql_history/query_history.py): `app/sql_history/query_history.py`

### Other components

- **Analyst**

## Connections

- Analyst → React App: asks
- React App → Collaborator Chat: shows chat
- Collaborator Chat → FastAPI Gateway: sends question
- FastAPI Gateway → SQL Agent: calls
- SQL Agent → Intent Router: routes intent
- Intent Router → Session Memory: resolves context
- Intent Router → Analyst Personas: dispatches modes
- Intent Router → Query Planner: plans analytics
- Query Planner → Knowledge Graph: resolves entities
- SQL Agent → Schema Retriever: retrieves context
- Schema Retriever → ChromaDB: queries embeddings
- SQL Agent → SQL Synthesizer: generates routine SQL
- SQL Agent → Ollama Qwen: generates complex SQL
- SQL Agent → SQL Validator: validates SQL
- SQL Validator → Read Executor: approves read query
- Read Executor → MySQL Database: executes read
- Read Executor → SQL Agent: returns rows
- SQL Agent → Results and Charts: returns results
- React App → Dashboard Views: opens views
- React App → Reports and Export: requests exports
- FastAPI Gateway → Query History: logs queries
- SQL Agent → Knowledge Graph: enriches successful queries