# datahub-project/analytics-agent architecture

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

- Interactive diagram: https://gitdiagram.com/datahub-project/analytics-agent
- Repository: https://github.com/datahub-project/analytics-agent

## Overview

Analytics Agent is a web application for asking warehouse questions in natural language and receiving SQL-backed results, charts, and conversational follow-ups. The main flow is browser chat to the chat API and LangGraph agent, which draws on configured LLMs and optional DataHub context, invokes a selected SQL or MCP engine, and streams responses back to the UI. The product also manages conversations, connections, OAuth, and settings. Relationships are limited to README statements and the supplied excerpts or source-index references; unsampled chat and UI internals are not assumed.

Main entry points: [`backend/src/analytics_agent/agent/graph.py`](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/agent/graph.py) (Agent graph), [`backend/src/analytics_agent/db/repository.py`](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/db/repository.py) (Persistence repositories), [`backend/src/analytics_agent/engines/factory.py`](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/engines/factory.py) (Engine registry), [`backend/src/analytics_agent/api/settings.py`](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/api/settings.py) (Settings API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_app["React app<br/>[App.tsx]"]
  node_chatui["Chat experience<br/>[ChatView.tsx]"]
  node_onboarding["Setup wizard"]
  node_settingsui["Settings and connections<br/>[SettingsModal.tsx]"]
end

subgraph group_api["API and persistence"]
  node_chatapi["Chat endpoint<br/>[chat.py]"]
  node_settingsapi["Settings API<br/>[settings.py]"]
  node_oauth["OAuth auth<br/>[oauth.py]"]
  node_conversationsapi["Conversation API<br/>[conversations.py]"]
  node_database[("Application database<br/>[base.py]")]
  node_repository["Persistence repositories<br/>[repository.py]"]
end

subgraph group_agent["Agent and context"]
  node_agentgraph["Agent graph<br/>[graph.py]"]
  node_llm["LLM providers<br/>[llm.py]"]
  node_charts["Chart generation<br/>[chart_generator.py]"]
  node_skills["DataHub skills<br/>[datahub_skills.py]"]
  node_datahub["DataHub context<br/>[datahub.py]"]
  node_contextmcp["MCP context platform<br/>[mcp_platform.py]"]
end

subgraph group_connections["Data connections"]
  node_enginefactory["Engine registry<br/>[factory.py]"]
  node_sqlengine["SQL query engine<br/>[engine.py]"]
  node_mcpengine["MCP query engine<br/>[engine.py]"]
  node_connectors["Warehouse connectors"]
end

node_user(("Analyst"))
node_warehouse[("Data warehouse")]
node_llmservice["LLM service"]
node_datahubservice["DataHub service"]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_chatui
node_app -->|"opens"| node_settingsui
node_chatui -.->|"sends chat"| node_chatapi
node_settingsui -.->|"configures"| node_settingsapi
node_onboarding -.->|"configures"| node_settingsapi
node_chatapi -.->|"runs"| node_agentgraph
node_chatapi -.->|"persists conversation"| node_repository
node_conversationsapi -.->|"reads and writes"| node_repository
node_settingsapi -->|"reads and writes"| node_repository
node_oauth -->|"stores credentials"| node_repository
node_repository -->|"queries"| node_database
node_agentgraph -.->|"requests completions"| node_llm
node_agentgraph -.->|"selects engine"| node_enginefactory
node_agentgraph -.->|"uses skills"| node_skills
node_agentgraph -.->|"generates charts"| node_charts
node_llm -.->|"calls provider"| node_llmservice
node_skills -->|"uses context"| node_datahub
node_datahub -.->|"queries metadata"| node_datahubservice
node_enginefactory -->|"creates"| node_sqlengine
node_enginefactory -->|"creates"| node_mcpengine
node_enginefactory -->|"configures"| node_connectors
node_sqlengine -->|"executes SQL"| node_warehouse
node_mcpengine -->|"discovers tools"| node_connectors
node_connectors -.->|"queries data"| node_warehouse
node_settingsapi -->|"tests connection"| node_contextmcp

click node_app "https://github.com/datahub-project/analytics-agent/blob/main/frontend/src/App.tsx"
click node_chatui "https://github.com/datahub-project/analytics-agent/blob/main/frontend/src/components/Chat/ChatView.tsx"
click node_onboarding "https://github.com/datahub-project/analytics-agent/blob/main/frontend/src/components/Onboarding/OnboardingWizard.tsx"
click node_settingsui "https://github.com/datahub-project/analytics-agent/blob/main/frontend/src/components/Settings/SettingsModal.tsx"
click node_chatapi "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/api/chat.py"
click node_settingsapi "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/api/settings.py"
click node_oauth "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/api/oauth.py"
click node_conversationsapi "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/api/conversations.py"
click node_database "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/db/base.py"
click node_repository "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/db/repository.py"
click node_agentgraph "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/agent/graph.py"
click node_llm "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/agent/llm.py"
click node_charts "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/agent/chart_generator.py"
click node_skills "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/skills/datahub_skills.py"
click node_datahub "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/context/datahub.py"
click node_contextmcp "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/context/mcp_platform.py"
click node_enginefactory "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/engines/factory.py"
click node_sqlengine "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/engines/sqlalchemy/engine.py"
click node_mcpengine "https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/engines/mcp/engine.py"
click node_connectors "https://github.com/datahub-project/analytics-agent/tree/main/connectors"

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_app,node_chatui,node_onboarding,node_settingsui toneBlue
class node_chatapi,node_settingsapi,node_oauth,node_conversationsapi,node_database,node_repository,node_warehouse toneAmber
class node_agentgraph,node_llm,node_charts,node_skills,node_datahub,node_contextmcp toneMint
class node_enginefactory,node_sqlengine,node_mcpengine,node_connectors toneRose
class node_user,node_llmservice,node_datahubservice toneIndigo
```

## Components

### Web interface

- [React app](https://github.com/datahub-project/analytics-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat experience](https://github.com/datahub-project/analytics-agent/blob/main/frontend/src/components/Chat/ChatView.tsx): `frontend/src/components/Chat/ChatView.tsx`
- [Setup wizard](https://github.com/datahub-project/analytics-agent/blob/main/frontend/src/components/Onboarding/OnboardingWizard.tsx): `frontend/src/components/Onboarding/OnboardingWizard.tsx`
- [Settings and connections](https://github.com/datahub-project/analytics-agent/blob/main/frontend/src/components/Settings/SettingsModal.tsx): `frontend/src/components/Settings/SettingsModal.tsx`

### API and persistence

- [Chat endpoint](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/api/chat.py): `backend/src/analytics_agent/api/chat.py`
- [Settings API](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/api/settings.py): `backend/src/analytics_agent/api/settings.py`
- [OAuth auth](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/api/oauth.py): `backend/src/analytics_agent/api/oauth.py`
- [Conversation API](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/api/conversations.py): `backend/src/analytics_agent/api/conversations.py`
- [Application database](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/db/base.py): `backend/src/analytics_agent/db/base.py`
- [Persistence repositories](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/db/repository.py): `backend/src/analytics_agent/db/repository.py`

### Agent and context

- [Agent graph](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/agent/graph.py): `backend/src/analytics_agent/agent/graph.py`
- [LLM providers](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/agent/llm.py): `backend/src/analytics_agent/agent/llm.py`
- [Chart generation](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/agent/chart_generator.py): `backend/src/analytics_agent/agent/chart_generator.py`
- [DataHub skills](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/skills/datahub_skills.py): `backend/src/analytics_agent/skills/datahub_skills.py`
- [DataHub context](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/context/datahub.py): `backend/src/analytics_agent/context/datahub.py`
- [MCP context platform](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/context/mcp_platform.py): `backend/src/analytics_agent/context/mcp_platform.py`

### Data connections

- [Engine registry](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/engines/factory.py): `backend/src/analytics_agent/engines/factory.py`
- [SQL query engine](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/engines/sqlalchemy/engine.py): `backend/src/analytics_agent/engines/sqlalchemy/engine.py`
- [MCP query engine](https://github.com/datahub-project/analytics-agent/blob/main/backend/src/analytics_agent/engines/mcp/engine.py): `backend/src/analytics_agent/engines/mcp/engine.py`
- [Warehouse connectors](https://github.com/datahub-project/analytics-agent/tree/main/connectors): `connectors`

### Other components

- **Analyst**
- **Data warehouse**
- **LLM service**
- **DataHub service**

## Connections

- Analyst → React app: uses (evidence: `README.md`)
- React app → Chat experience: renders (evidence: `frontend/src/App.tsx`)
- React app → Settings and connections: opens (evidence: `frontend/src/App.tsx`)
- Chat experience → Chat endpoint: sends chat
- Settings and connections → Settings API: configures
- Setup wizard → Settings API: configures
- Chat endpoint → Agent graph: runs
- Chat endpoint → Persistence repositories: persists conversation
- Conversation API → Persistence repositories: reads and writes
- Settings API → Persistence repositories: reads and writes (evidence: `backend/src/analytics_agent/api/settings.py`)
- OAuth auth → Persistence repositories: stores credentials (evidence: `backend/src/analytics_agent/api/oauth.py`)
- Persistence repositories → Application database: queries (evidence: `backend/src/analytics_agent/db/repository.py`)
- Agent graph → LLM providers: requests completions
- Agent graph → Engine registry: selects engine
- Agent graph → DataHub skills: uses skills
- Agent graph → Chart generation: generates charts
- LLM providers → LLM service: calls provider
- DataHub skills → DataHub context: uses context (evidence: `backend/src/analytics_agent/skills/datahub_skills.py`)
- DataHub context → DataHub service: queries metadata
- Engine registry → SQL query engine: creates (evidence: `backend/src/analytics_agent/engines/factory.py`)
- Engine registry → MCP query engine: creates (evidence: `backend/src/analytics_agent/engines/factory.py`)
- Engine registry → Warehouse connectors: configures (evidence: `backend/src/analytics_agent/engines/factory.py`)
- SQL query engine → Data warehouse: executes SQL (evidence: `README.md`)
- MCP query engine → Warehouse connectors: discovers tools (evidence: `backend/src/analytics_agent/engines/mcp/engine.py`)
- Warehouse connectors → Data warehouse: queries data
- Settings API → MCP context platform: tests connection (evidence: `backend/src/analytics_agent/api/settings.py`)
