# nirmalkumar31/agentic-analytics-engine architecture

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

- Interactive diagram: https://gitdiagram.com/nirmalkumar31/agentic-analytics-engine
- Repository: https://github.com/nirmalkumar31/agentic-analytics-engine
- Video tour (about a minute): https://gitdiagram.com/nirmalkumar31/agentic-analytics-engine/video

## Overview

Agentic Analytics Engine accepts a demo or uploaded CSV/Parquet table, maps a business question to a constrained analytical plan, computes it, and returns an answer with SQL, rows, and an MCP trace. The principal path runs from browser/API through session setup and LangGraph interpretation, MCP aggregation, guarded DuckDB execution, and evidence verification. Distinct capabilities include optional AI disambiguation and correlation. Source excerpts establish the main calls; documented capabilities without sampled callers are shown without inferred links.

Main entry points: [`workflow.py`](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/workflow.py) (LangGraph Workflow), [`mcp_server.py`](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py) (MCP Tool Server), [`app.py`](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/app.py) (FastAPI Sessions), [`engine.py`](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py) (Guarded SQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_browser["Browser UI<br/>[index.html]"]
  node_api["FastAPI Sessions<br/>[app.py]"]
  node_dataset[("Session Dataset<br/>[engine.py]")]
end

subgraph group_workflow["Question Workflow"]
  node_graph["LangGraph Workflow<br/>[workflow.py]"]
  node_ai["AI Planner<br/>[workflow.py]"]
  node_evidence["Evidence Check<br/>[workflow.py]"]
end

subgraph group_analytics["Analytics Engine"]
  node_resolver["Rule Resolver<br/>[engine.py]"]
  node_validator["Plan Validator<br/>[engine.py]"]
  node_sql["Guarded SQL<br/>[engine.py]"]
  node_duckdb[("DuckDB Results<br/>[engine.py]")]
  node_snapshot[("Result Snapshot<br/>[engine.py]")]
end

subgraph group_tools["MCP Tools"]
  node_mcp["MCP Tool Server<br/>[mcp_server.py]"]
  node_aggregate["Aggregate Tool<br/>[mcp_server.py]"]
  node_correlation["Correlation Tool<br/>[mcp_server.py]"]
  node_profile["Dataset Profile<br/>[mcp_server.py]"]
  node_result_tool["Result Retrieval<br/>[mcp_server.py]"]
end

node_user(("Analyst"))
node_ai_service["AI Provider"]

node_user -->|"asks question"| node_browser
node_browser -.->|"sends requests"| node_api
node_api -->|"loads data"| node_dataset
node_api -->|"invokes analysis"| node_graph
node_graph -->|"resolves question"| node_resolver
node_graph -->|"requests proposal"| node_ai
node_ai -->|"requests mapping"| node_ai_service
node_graph -->|"validates proposal"| node_validator
node_graph -->|"builds server"| node_mcp
node_graph -->|"calls tool"| node_aggregate
node_aggregate -->|"executes plan"| node_sql
node_sql -->|"runs query"| node_duckdb
node_sql -->|"records result"| node_snapshot
node_graph -->|"checks result"| node_evidence
node_evidence -->|"verifies values"| node_snapshot
node_mcp -->|"registers tool"| node_correlation
node_mcp -->|"registers tool"| node_profile
node_mcp -->|"registers tool"| node_result_tool

click node_browser "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/static/index.html"
click node_api "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/app.py"
click node_dataset "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py"
click node_graph "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/workflow.py"
click node_resolver "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py"
click node_ai "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/workflow.py"
click node_validator "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py"
click node_mcp "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py"
click node_aggregate "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py"
click node_sql "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py"
click node_duckdb "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py"
click node_snapshot "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py"
click node_evidence "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/workflow.py"
click node_correlation "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py"
click node_profile "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py"
click node_result_tool "https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.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_browser,node_api,node_dataset toneBlue
class node_graph,node_ai,node_evidence toneAmber
class node_resolver,node_validator,node_sql,node_duckdb,node_snapshot toneMint
class node_mcp,node_aggregate,node_correlation,node_profile,node_result_tool toneRose
class node_user,node_ai_service toneIndigo
```

## Components

### User Interface

- [Browser UI](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/static/index.html): `static/index.html`
- [FastAPI Sessions](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/app.py): `app.py`
- [Session Dataset](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py): `engine.py`

### Question Workflow

- [LangGraph Workflow](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/workflow.py): `workflow.py`
- [AI Planner](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/workflow.py): `workflow.py`
- [Evidence Check](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/workflow.py): `workflow.py`

### Analytics Engine

- [Rule Resolver](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py): `engine.py`
- [Plan Validator](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py): `engine.py`
- [Guarded SQL](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py): `engine.py`
- [DuckDB Results](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py): `engine.py`
- [Result Snapshot](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/engine.py): `engine.py`

### MCP Tools

- [MCP Tool Server](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py): `mcp_server.py`
- [Aggregate Tool](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py): `mcp_server.py`
- [Correlation Tool](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py): `mcp_server.py`
- [Dataset Profile](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py): `mcp_server.py`
- [Result Retrieval](https://github.com/nirmalkumar31/agentic-analytics-engine/blob/main/mcp_server.py): `mcp_server.py`

### Other components

- **Analyst**
- **AI Provider**

## Connections

- Analyst → Browser UI: asks question (evidence: `README.md`)
- Browser UI → FastAPI Sessions: sends requests
- FastAPI Sessions → Session Dataset: loads data (evidence: `app.py`)
- FastAPI Sessions → LangGraph Workflow: invokes analysis (evidence: `app.py`)
- LangGraph Workflow → Rule Resolver: resolves question (evidence: `workflow.py`)
- LangGraph Workflow → AI Planner: requests proposal (evidence: `workflow.py`)
- AI Planner → AI Provider: requests mapping (evidence: `workflow.py`)
- LangGraph Workflow → Plan Validator: validates proposal (evidence: `workflow.py`)
- LangGraph Workflow → MCP Tool Server: builds server (evidence: `workflow.py`)
- LangGraph Workflow → Aggregate Tool: calls tool (evidence: `workflow.py`)
- Aggregate Tool → Guarded SQL: executes plan (evidence: `mcp_server.py`)
- Guarded SQL → DuckDB Results: runs query (evidence: `engine.py`)
- Guarded SQL → Result Snapshot: records result (evidence: `engine.py`)
- LangGraph Workflow → Evidence Check: checks result (evidence: `workflow.py`)
- Evidence Check → Result Snapshot: verifies values (evidence: `workflow.py`)
- MCP Tool Server → Correlation Tool: registers tool (evidence: `mcp_server.py`)
- MCP Tool Server → Dataset Profile: registers tool (evidence: `mcp_server.py`)
- MCP Tool Server → Result Retrieval: registers tool (evidence: `mcp_server.py`)
