Project guide
Governed Metric Execution Architecture
This project is an engineering architecture case study for a governed analytics execution path. It documents how natural-language questions about revenue, token usage, and quota can be constrained to approved dbt and MetricFlow semantic contracts instead of allowing an LLM to generate raw SQL.
Architecture Goal
The goal is to define a defensible execution architecture for AI-assisted analytics: natural language enters the system, the model selects from a governed metric surface, the backend validates that selection against the semantic manifest, and MetricFlow owns query planning and execution.
The case study focuses on the domains already modeled in the warehouse: revenue, token usage, and quota or capacity. Customer-service workflows and multi-step root-cause agents are intentionally outside the architecture boundary for this version.
The core engineering constraint is explicit: the LLM may choose from governed metrics, but it cannot invent metrics or produce executable SQL.
Why It Matters
LLM analytics systems fail when the model becomes the source of truth. This project frames the safer architecture: use the model as a selector, keep metric definitions in dbt and MetricFlow, and make every answer traceable to a governed semantic contract.
The repository documents the system boundaries, architecture decisions, metric dictionary, implementation plan, QA gates, and launch-readiness checks so the work can be reviewed as an engineering design rather than a dashboard demo.
Architecture Shape
- Data layer: dbt medallion models with governed gold tables and MetricFlow metrics.
- Semantic layer: 69 governed metrics across revenue, token usage, and quota.
- Execution layer: FastAPI orchestration that validates metric, dimension, and filter selections before MetricFlow execution.
- AI boundary: provider-agnostic LLM configuration restricted to governed metric selection.
- Architecture docs: project decisions, data design, software design, implementation plan, and acceptance gates live under
doc/.
How To Explore It
1. Open The Repository
Start with the GitHub project to inspect the dbt models, MetricFlow setup, service boundary, and architecture documentation.
https://github.com/btg-case-studies-with-dbt/single-dbt-opensource
2. Read The Report Docs
Begin with doc/10.TRD_CONCISE.md, doc/13.DATA_ARCHITECTURE.md, doc/14.SOFTWARE_ARCHITECTURE.md, doc/15.DATA_IMPLEMENTATION_PLAN.md, and doc/16.SOFTWARE_IMPLEMENTATION_PLAN.md. Those explain the technical requirements, metric contract, system boundaries, and implementation plan.
3. Run The Local Stack
Use the repository setup guide to start the local Postgres, dbt, Airflow, semantic-layer, and API pieces. The stack is intended for local architecture inspection rather than hosted production use.
Current Status
The semantic layer and architecture documentation are available in the public repository. The local prototype proves the governed execution path before expanding into production hosting or more complex agentic investigations.