01 — Reference architecture
Seven layers, one boundary that matters more than the rest.
Conventional at the data layers, opinionated at the reasoning layer. The decision that matters is exactly where determinism ends and generation begins — and proving that line held on every request.
1.1
Layer stack
Read top-down for user experience, bottom-up for build order. Tap a layer for detail.
Conversational surfaces inside the tools people already use, embedded reports, and purpose-built web surfaces for stateful workflows. Any action with a financial consequence has a confirmation step showing exactly what will be written and by whom.
Chat surfaceWorkspace agentsEmbedded reportsApproval appsEmail
Design decision — cross-cutting concerns
Identity, secrets, audit, cost control, prompt/model registry and environment promotion cut across all seven layers and are built once at platform level — not seven times.
Assumption — platform availability
We assume the semantic layer, tenant and warehouse are addressable programmatically from a governed identity, and a non-production environment exists or can be created.
1.2
The determinism boundary
Above the line: generated, must be grounded and cited. Below: computed and reproducible.
QuestionIntent / synonym resolution⟊Measure or calc callValue + lineageNarration + citation
Model may
- Map a question to a registered measure/tool
- Fill a typed tool-call argument schema
- Explain a value using cited knowledge
- Say it cannot answer
Model never
- Emits a figure it did not receive from a tool
- Writes raw queries directly against production tables
- Invents a measure outside the registry
- Changes state without an approval step
Enforced by
- Numeric-token reconciliation against tool results
- Tool allow-list per agent/role
- Schema validation on every tool output
- Traced runs; unmatched figure = test failure
▸Why not free-form query generation against the warehouse
Free-form generated queries demo well on day one but bypasses the approved metric definition, bypasses row-level security unless every path is separately secured, and fails silently — a wrong join produces a plausible number, not an error. Where genuine ad-hoc exploration is needed, we would route it to a sandboxed, clearly-labelled mode with its own permissions, separate from the trusted answer path.
1.3Identity and permission propagationImplementation
1.4Walkthrough A — industrialising a spreadsheet calculation modelImplementation
1.5Walkthrough B — a governed natural-language reporting answerImplementation
1.6Environments, promotion and change controlImplementation