# ishan-debugg/definitiondrift architecture

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

- Interactive diagram: https://gitdiagram.com/ishan-debugg/definitiondrift
- Repository: https://github.com/ishan-debugg/definitiondrift

## Overview

DefinitionDrift is a governed natural-language analytics product: users ask questions, the system classifies intent and checks metric definitions for conflicts, then generates and validates SQL before returning results. Conflicts pause for human review; approved definitions and query history support repeatable answers, while schema-drift monitoring flags definitions affected by data changes. The Next.js app and MCP server provide user-facing and tool-based entry points. Some runtime wiring is unsampled, so the graph omits uncertain links and shows documented capabilities at their known source paths.

Main entry points: [`api/main.py`](https://github.com/ishan-debugg/definitiondrift/blob/main/api/main.py) (FastAPI), [`agents/orchestrator.py`](https://github.com/ishan-debugg/definitiondrift/blob/main/agents/orchestrator.py) (Query Orchestrator), [`frontend-next/app/ask-data/page.tsx`](https://github.com/ishan-debugg/definitiondrift/blob/main/frontend-next/app/ask-data/page.tsx) (Ask Data), [`mcp_server/server.py`](https://github.com/ishan-debugg/definitiondrift/blob/main/mcp_server/server.py) (MCP Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Interfaces"]
  node_ask["Ask Data<br/>[page.tsx]"]
  node_definitions_ui["Definitions UI<br/>[page.tsx]"]
  node_hitl_ui["HITL Queue UI<br/>[page.tsx]"]
  node_analytics_ui["Analytics UI<br/>[page.tsx]"]
  node_api["FastAPI<br/>[main.py]"]
end

subgraph group_query["Governed Query"]
  node_orchestrator["Query Orchestrator<br/>[orchestrator.py]"]
  node_intent["Intent Router<br/>[intent_router.py]"]
  node_core["Conflict and Query Agent<br/>[core.py]"]
  node_validator["SQL Validator<br/>[sql_validator.py]"]
end

subgraph group_governance["Metric Governance"]
  node_embeddings["Embedding Search<br/>[engine.py]"]
  node_registry[("Definition Registry<br/>[db.py]")]
  node_hitl[("Conflict Review<br/>[db.py]")]
  node_drift["Schema Drift Monitor<br/>[orchestrator.py]"]
end

subgraph group_data["Data and State"]
  node_history[("Query History<br/>[db.py]")]
  node_data_db[("Business Database<br/>[connection.py]")]
  node_chat_memory[("Conversation Store<br/>[conversation.py]")]
end

subgraph group_integration["External Interfaces"]
  node_mcp["MCP Tools<br/>[server.py]"]
  node_llm["LLM Router<br/>[llm_router.py]"]
  node_llm_service["LLM Providers"]
end

node_analyst(("Analyst"))
node_admin(("Data Engineer"))

node_analyst -->|"asks question"| node_ask
node_ask -->|"submits query"| node_api
node_api -->|"runs query"| node_orchestrator
node_orchestrator -->|"classifies intent"| node_intent
node_intent -.->|"classifies ambiguous"| node_llm
node_orchestrator -->|"checks conflict"| node_core
node_core -->|"searches definitions"| node_embeddings
node_core -->|"reads definitions"| node_registry
node_orchestrator -->|"queues conflict"| node_hitl
node_admin -->|"reviews conflicts"| node_hitl_ui
node_hitl_ui -->|"resolves conflict"| node_api
node_api -->|"updates resolution"| node_hitl
node_admin -->|"manages metrics"| node_definitions_ui
node_definitions_ui -->|"uses API"| node_api
node_api -->|"manages definitions"| node_registry
node_orchestrator -->|"generates SQL"| node_llm
node_llm -->|"calls provider"| node_llm_service
node_orchestrator -->|"validates SQL"| node_validator
node_orchestrator -->|"executes query"| node_data_db
node_orchestrator -->|"logs query"| node_history
node_ask -->|"sends feedback"| node_api
node_api -->|"stores feedback"| node_history
node_orchestrator -->|"checks schema"| node_drift
node_drift -->|"inspects schema"| node_data_db
node_drift -->|"records drift"| node_registry
node_ask -->|"uses query API"| node_api
node_analyst -.->|"uses tools"| node_mcp
node_mcp -->|"checks query conflict"| node_core
node_mcp -->|"lists definitions"| node_registry
node_mcp -->|"resolves conflicts"| node_hitl
node_api -->|"stores sessions"| node_chat_memory
node_analytics_ui -->|"requests analytics"| node_api

click node_ask "https://github.com/ishan-debugg/definitiondrift/blob/main/frontend-next/app/ask-data/page.tsx"
click node_definitions_ui "https://github.com/ishan-debugg/definitiondrift/blob/main/frontend-next/app/definitions/page.tsx"
click node_hitl_ui "https://github.com/ishan-debugg/definitiondrift/blob/main/frontend-next/app/hitl/page.tsx"
click node_analytics_ui "https://github.com/ishan-debugg/definitiondrift/blob/main/frontend-next/app/analytics/page.tsx"
click node_api "https://github.com/ishan-debugg/definitiondrift/blob/main/api/main.py"
click node_mcp "https://github.com/ishan-debugg/definitiondrift/blob/main/mcp_server/server.py"
click node_orchestrator "https://github.com/ishan-debugg/definitiondrift/blob/main/agents/orchestrator.py"
click node_intent "https://github.com/ishan-debugg/definitiondrift/blob/main/agents/intent_router.py"
click node_core "https://github.com/ishan-debugg/definitiondrift/blob/main/agents/core.py"
click node_validator "https://github.com/ishan-debugg/definitiondrift/blob/main/agents/sql_validator.py"
click node_llm "https://github.com/ishan-debugg/definitiondrift/blob/main/agents/llm_router.py"
click node_embeddings "https://github.com/ishan-debugg/definitiondrift/blob/main/embeddings/engine.py"
click node_registry "https://github.com/ishan-debugg/definitiondrift/blob/main/store/db.py"
click node_hitl "https://github.com/ishan-debugg/definitiondrift/blob/main/store/db.py"
click node_drift "https://github.com/ishan-debugg/definitiondrift/blob/main/agents/orchestrator.py"
click node_history "https://github.com/ishan-debugg/definitiondrift/blob/main/store/db.py"
click node_data_db "https://github.com/ishan-debugg/definitiondrift/blob/main/db/connection.py"
click node_chat_memory "https://github.com/ishan-debugg/definitiondrift/blob/main/store/conversation.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_ask,node_definitions_ui,node_hitl_ui,node_analytics_ui,node_api toneBlue
class node_orchestrator,node_intent,node_core,node_validator toneAmber
class node_embeddings,node_registry,node_hitl,node_drift toneMint
class node_history,node_data_db,node_chat_memory toneRose
class node_mcp,node_llm,node_llm_service,node_analyst,node_admin toneIndigo
```

## Components

### User Interfaces

- [Ask Data](https://github.com/ishan-debugg/definitiondrift/blob/main/frontend-next/app/ask-data/page.tsx): `frontend-next/app/ask-data/page.tsx`
- [Definitions UI](https://github.com/ishan-debugg/definitiondrift/blob/main/frontend-next/app/definitions/page.tsx): `frontend-next/app/definitions/page.tsx`
- [HITL Queue UI](https://github.com/ishan-debugg/definitiondrift/blob/main/frontend-next/app/hitl/page.tsx): `frontend-next/app/hitl/page.tsx`
- [Analytics UI](https://github.com/ishan-debugg/definitiondrift/blob/main/frontend-next/app/analytics/page.tsx): `frontend-next/app/analytics/page.tsx`
- [FastAPI](https://github.com/ishan-debugg/definitiondrift/blob/main/api/main.py): `api/main.py`

### Governed Query

- [Query Orchestrator](https://github.com/ishan-debugg/definitiondrift/blob/main/agents/orchestrator.py): `agents/orchestrator.py`
- [Intent Router](https://github.com/ishan-debugg/definitiondrift/blob/main/agents/intent_router.py): `agents/intent_router.py`
- [Conflict and Query Agent](https://github.com/ishan-debugg/definitiondrift/blob/main/agents/core.py): `agents/core.py`
- [SQL Validator](https://github.com/ishan-debugg/definitiondrift/blob/main/agents/sql_validator.py): `agents/sql_validator.py`

### Metric Governance

- [Embedding Search](https://github.com/ishan-debugg/definitiondrift/blob/main/embeddings/engine.py): `embeddings/engine.py`
- [Definition Registry](https://github.com/ishan-debugg/definitiondrift/blob/main/store/db.py): `store/db.py`
- [Conflict Review](https://github.com/ishan-debugg/definitiondrift/blob/main/store/db.py): `store/db.py`
- [Schema Drift Monitor](https://github.com/ishan-debugg/definitiondrift/blob/main/agents/orchestrator.py): `agents/orchestrator.py`

### Data and State

- [Query History](https://github.com/ishan-debugg/definitiondrift/blob/main/store/db.py): `store/db.py`
- [Business Database](https://github.com/ishan-debugg/definitiondrift/blob/main/db/connection.py): `db/connection.py`
- [Conversation Store](https://github.com/ishan-debugg/definitiondrift/blob/main/store/conversation.py): `store/conversation.py`

### External Interfaces

- [MCP Tools](https://github.com/ishan-debugg/definitiondrift/blob/main/mcp_server/server.py): `mcp_server/server.py`
- [LLM Router](https://github.com/ishan-debugg/definitiondrift/blob/main/agents/llm_router.py): `agents/llm_router.py`
- **LLM Providers**

### Other components

- **Analyst**
- **Data Engineer**

## Connections

- Analyst → Ask Data: asks question
- Ask Data → FastAPI: submits query
- FastAPI → Query Orchestrator: runs query
- Query Orchestrator → Intent Router: classifies intent
- Intent Router → LLM Router: classifies ambiguous
- Query Orchestrator → Conflict and Query Agent: checks conflict
- Conflict and Query Agent → Embedding Search: searches definitions
- Conflict and Query Agent → Definition Registry: reads definitions
- Query Orchestrator → Conflict Review: queues conflict
- Data Engineer → HITL Queue UI: reviews conflicts
- HITL Queue UI → FastAPI: resolves conflict
- FastAPI → Conflict Review: updates resolution
- Data Engineer → Definitions UI: manages metrics
- Definitions UI → FastAPI: uses API
- FastAPI → Definition Registry: manages definitions
- Query Orchestrator → LLM Router: generates SQL
- LLM Router → LLM Providers: calls provider
- Query Orchestrator → SQL Validator: validates SQL
- Query Orchestrator → Business Database: executes query
- Query Orchestrator → Query History: logs query
- Ask Data → FastAPI: sends feedback
- FastAPI → Query History: stores feedback
- Query Orchestrator → Schema Drift Monitor: checks schema
- Schema Drift Monitor → Business Database: inspects schema
- Schema Drift Monitor → Definition Registry: records drift
- Ask Data → FastAPI: uses query API
- Analyst → MCP Tools: uses tools
- MCP Tools → Conflict and Query Agent: checks query conflict
- MCP Tools → Definition Registry: lists definitions
- MCP Tools → Conflict Review: resolves conflicts
- FastAPI → Conversation Store: stores sessions
- Analytics UI → FastAPI: requests analytics