Analytical surfaces README
The analytical-surfaces module is the final role explainer for Module 13. Its source README lives at tutorial/analytical-surfaces/README.md.
ADR-0006 splits the tutorial platform into two contracts by audience: the app contract for application clients and the analytical contract for analysts working over DuckDB/Parquet-backed tables. Module 13 is a categorical enrichment of that two-contracts model: the analytical contract has internal differentiation by analyst need, not just by audience. ADR-0004 is the platform-as-leverage thesis behind the module: editorial accountability belongs in platform surfaces that make constraints legible, testable, and tunable.
- Tier 1 - static file generator: Evidence, Observable, and Quarto produce durable authored pages from SQL, prose, and charts.
- Tier 2 - self-hostable BI: Metabase and Rill provide a local interactive BI loop for filtering, dashboard editing, and follow-up questions.
- Tier 3 - conversational / AI-IDE: nao gives the analyst an editor-like surface where schema context, examples, rules, and answer tests sit beside natural-language analysis.
The production Analyst dashboards surface now uses Observable
Framework, as recorded in
ADR-0025.
ADR-0026
records Metabase as the Tier 2 BI winner.
ADR-0023
frames nao as the Tier 3 analytical-agent surface. Module 13 does not restore
the demoted /explore page or pretend one dashboard tool can answer every
analyst workflow.
When to use which
Section titled “When to use which”| Analyst task | Tier 1 - Observable static artefact | Tier 2 - Metabase live BI | Tier 3 - nao AI-IDE |
|---|---|---|---|
| Publish the recurring executive reference view for NDCG@10, diversity, and constraint status. | Use Tier 1 so the answer is a reviewed build artefact at /dashboard/. | Use Tier 2 only to explore variants before publishing. | Use Tier 3 to draft or check the SQL behind the page. |
| Investigate why Adressa behaves differently from EB-NeRD on a constraint metric. | Use Tier 1 for the permanent comparison once the finding is known. | Use Tier 2 for interactive publisher filters, saved questions, and follow-up charts. | Use Tier 3 to ask schema-aware questions and inspect lineage while shaping the query. |
| Explain how a MIND taxonomy mismatch changes downstream dashboard numbers. | Use Tier 1 for a stable reader-facing note. | Use Tier 2 to pivot by category, run comparisons, and save the analyst view. | Use Tier 3 to get a before/after SQL diff and trace affected columns. |
| Add a new analytical question to the tutorial from raw DuckDB/Parquet tables. | Use Tier 1 when the question has become a durable module page. | Use Tier 2 when the question needs live slicing before it is settled. | Use Tier 3 when the analyst is still authoring, testing, and revising the query. |
Each tier makes a different kind of accountability operable. Tier 1 makes the platform’s behaviour permanently inspectable as a build artefact. Tier 2 makes the analyst’s investigation interactive in a live BI session, so follow-up questions and saved views remain visible. Tier 3 amplifies the analyst’s own authoring loop with schema context, tests, and diffs before an answer graduates into a public surface.
Hex is rejected because it is SaaS-first and fails the ADR-0014 local-first constraint. The candidates that remain must be runnable against the same local analytical contract the rest of the tutorial uses.
The scaffold points to the real comparison lessons: the Tier 1 static-surface verdict, Tier 2 Metabase vs Rill verdict, Tier 2 production deploy, and Tier 3 nao walkthrough. Those lessons are product work in tutorial form; their verdicts decide which surfaces become the production-shape analytical experience.