Low Dashboards system

KPI Definition Sheet & Glossary

A single source-of-truth document plus a lightweight in-app glossary that pins down every metric used across the dashboards — exact formula, numerator, denominator, time basis, included/excluded buckets, refresh cadence, and owner — so 'conversion rate', 'active lead', and 'no-show' mean exactly one thing. It is the governance artifact every other system in this suite references. It defines metrics; it does not compute them, but it is what makes the computations trustworthy and consistent.

Start a ProjectAll Systems
3 to 6 days
timeline
Low
complexity
4
tools
4
steps

Built with real HMX dashboard tool paths

Markdown/doc in repoSQL reference snippetsNext.js 16 (glossary route/tooltips)Version control (git)Markdown/doc in repoSQL reference snippetsNext.js 16 (glossary route/tooltips)Version control (git)

01 // System facts

System facts

KPI Definition Sheet & Glossary uses a reporting model and review layer for Dashboards. A single source-of-truth document plus a lightweight in-app glossary that pins down every metric used across the dashboards — exact formula, numera... The architecture connects inventory every metric, markdown/doc in repo, sql reference snippets, and reporting view with an explicit control path.

Outcome

Ends metric ambiguity — every dashboard, report, and conversation uses identical definitions, so numbers are comparable across time and people and no one relitigates what a KPI means.

Main risk

The sheet rots: definitions change in SQL but the doc/tooltips aren't updated, so the glossary becomes confidently wrong — worse than none.

Prevention

Keep definitions version-controlled next to the queries, reference the same source in-app, and treat any metric change as requiring a paired sheet update via the changelog.

Fallback

If full in-app wiring isn't feasible, ship the version-controlled sheet alone as the single reference and link to it from each dashboard until tooltips are added.

System architecture

KPI Definition Sheet & Glossary Architecture

6 nodes
Inventory every metric
the canonical KPI sheet and
Markdown/doc in repo
SQL reference snippets
Review Queue
Reporting View
  1. 01Inventory every metric

    A single source-of-truth document plus a lightweight in-app glossary that pins down every metric used across the dashboards — exact formula, numera...

  2. 02the canonical KPI sheet and

    Write the canonical KPI sheet (one entry per metric: definition, SQL reference, owner, cadence, gotchas) and store it in the repo/docs so it is version-controlled alongside the code.

  3. 03Markdown/doc in repo

    Markdown/doc in repo contributes the trusted model for KPI Definition Sheet & Glossary so metrics are defined before they are visualized.

  4. 04SQL reference snippets

    Expose the definitions in-app: a glossary route or hover/tooltip on each metric label that pulls from the same source, so the chart and its definition can't drift apart.

  5. 05Review Queue

    If full in-app wiring isn't feasible, ship the version-controlled sheet alone as the single reference and link to it from each dashboard until tool...

  6. 06Reporting View

    Ends metric ambiguity — every dashboard, report, and conversation uses identical definitions, so numbers are comparable across time and people and...

How it is built

Build steps

A single source-of-truth document plus a lightweight in-app glossary that pins down every metric used across the dashboards — exact formula, numerator, denominator, time basis, included/excluded buckets, refresh cadence, and owner — so 'conversion rate', 'active lead', and 'no-show' mean exactly one thing. It is the governance artifact every other system in this suite references. It defines metrics; it does not compute them, but it is what makes the computations trustworthy and consistent.

  1. 01Inventory every metric currently shown across the dashboard suite and interview the owner to nail each definition (formula, time basis, exclusions, the edge cases people argue about).
  2. 02Write the canonical KPI sheet (one entry per metric: definition, SQL reference, owner, cadence, gotchas) and store it in the repo/docs so it is version-controlled alongside the code.
  3. 03Expose the definitions in-app: a glossary route or hover/tooltip on each metric label that pulls from the same source, so the chart and its definition can't drift apart.
  4. 04Add a review cadence and a 'definition changed' changelog so any metric redefinition is deliberate, dated, and reflected everywhere at once.

Tools

Workflow surface

  • Markdown/doc in repo
  • SQL reference snippets
  • Next.js 16 (glossary route/tooltips)
  • Version control (git)
  • Inputs layer: Inventory every metric currently shown across the dashboard suite and interview the owner to nail each definition (formula, time basis, exclusions, the edge cases people argue about).
  • Transform layer: Write the canonical KPI sheet (one entry per metric: definition, SQL reference, owner, cadence, gotchas) and store it in the repo/docs so it is version-controlled alongside the code.
  • Metrics layer: Markdown/doc in repo contributes the trusted model for KPI Definition Sheet & Glossary so metrics are defined before they are visualized.
  • Visualization layer: SQL reference snippets handles refresh, review, or reporting delivery while keep definitions version-controlled next to the queries, reference the same source in-app, and treat any metric change as requiring a paired sheet...
  • Action layer: Ends metric ambiguity — every dashboard, report, and conversation uses identical definitions, so numbers are comparable across time and people and...

Data flow

  1. 01Inventory every metric currently shown across the dashboard suite and interview the owner to nail each definition (formula, time basis, exclusions, the edge cases people argue about).
  2. 02Write the canonical KPI sheet (one entry per metric: definition, SQL reference, owner, cadence, gotchas) and store it in the repo/docs so it is version-controlled alongside the code.
  3. 03Expose the definitions in-app: a glossary route or hover/tooltip on each metric label that pulls from the same source, so the chart and its definition can't drift apart.
  4. 04Add a review cadence and a 'definition changed' changelog so any metric redefinition is deliberate, dated, and reflected everywhere at once.

Controls and fallbacks

  • The sheet rots: definitions change in SQL but the doc/tooltips aren't updated, so the glossary becomes confidently wrong — worse than none.
  • Keep definitions version-controlled next to the queries, reference the same source in-app, and treat any metric change as requiring a paired sheet...
  • If full in-app wiring isn't feasible, ship the version-controlled sheet alone as the single reference and link to it from each dashboard until tool...

Research basis