How ishan-debugg/definitiondrift works
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: main.py FastAPI · orchestrator.py Query Orchestrator · page.tsx Ask Data · server.py MCP Tools
Components 21
User Interfaces
- Ask Data
frontend-next/app/ask-data/page.tsx - Definitions UI
frontend-next/app/definitions/page.tsx - HITL Queue UI
frontend-next/app/hitl/page.tsx - Analytics UI
frontend-next/app/analytics/page.tsx - FastAPI
api/main.py
Governed Query
- Query Orchestrator
agents/orchestrator.py - Intent Router
agents/intent_router.py - Conflict and Query Agent
agents/core.py - SQL Validator
agents/sql_validator.py
Metric Governance
- Embedding Search
embeddings/engine.py - Definition Registry
store/db.py - Conflict Review
store/db.py - Schema Drift Monitor
agents/orchestrator.py
Data and State
- Query History
store/db.py - Business Database
db/connection.py - Conversation Store
store/conversation.py
External Interfaces
- MCP Tools
mcp_server/server.py - LLM Router
agents/llm_router.py - LLM Providers
Other components
- Analyst
- Data Engineer
Connections 32
- 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