Dashboards & Analytics · KPI Definitions

KPI Definition Cleanup Before Any Reporting

A definition pass that nails down what each KPI actually means and encodes it in SQL, so every later chart counts the same thing the same way.

Start a ProjectAll Case Studies
3 to 6 days
build time
4
outcomes
5
stack tools
6
build steps

Built with real HMX dashboard tool paths

Supabase PostgresCanonical SQL definition viewsMarkdown KPI dictionaryMetabase (shared models)Next.js 16 (consumes the views)Supabase PostgresCanonical SQL definition viewsMarkdown KPI dictionaryMetabase (shared models)Next.js 16 (consumes the views)

01 // Outcomes

Outcome signals

One
agreed definition per KPI, written down
Canonical
SQL views every later report reads from
Plain-language
KPI dictionary owners can actually read
Consistent
numbers across every downstream chart

Case architecture

KPI Definition Cleanup Before Any Architecture

6 nodes
Collect every KPI in use and
a definition session to
Supabase Postgres
Canonical SQL definition
Review Queue
Owner Review
  1. 01Collect every KPI in use and

    A definition pass that nails down what each KPI actually means and encodes it in SQL, so every later chart counts the same thing the same way.

  2. 02a definition session to

    Run a definition session to agree numerator, denominator, window, and filters for each KPI.

  3. 03Supabase Postgres

    Supabase Postgres contributes the trusted model for KPI Definition Cleanup Before Any so metrics are defined before they are visualized.

  4. 04Canonical SQL definition

    Implement each agreed KPI as one canonical view so there is a single source for the number.

  5. 05Review Queue

    When automation confidence is low, route the record to a manual owner with the source, stage, and last action attached.

  6. 06Owner Review

    One agreed definition per KPI, written down; Canonical SQL views every later report reads from; Plain-language KPI dictionary owners can actually r...

Problem

The operating gap

Two reports show different numbers for the same 'conversion rate' because nobody agreed what counts as a lead, a qualified lead, or a conversion — so every dashboard built on fuzzy definitions inherits the argument.

Build

What gets built

A short, deliberate cleanup that writes down each KPI's exact definition (numerator, denominator, window, filters) and implements it as a single canonical SQL view that every later dashboard reads from. The deliverable is the agreed definitions plus the views that enforce them — the foundation other reports build on.

Build steps

How it ships

KPI Definition Cleanup Before Any Reporting uses a reporting model and review layer for Dashboards. A definition pass that nails down what each KPI actually means and encodes it in SQL, so every later chart counts the same thing the same way. The architecture connects collect every kpi in use and, supabase postgres, canonical sql definition, and owner review with an explicit control path.

  1. 01Collect every KPI in use and capture how each is currently (mis)calculated across tools.
  2. 02Run a definition session to agree numerator, denominator, window, and filters for each KPI.
  3. 03Implement each agreed KPI as one canonical view so there is a single source for the number.
  4. 04Write a plain-language KPI dictionary so non-technical owners can read the definitions.
  5. 05Point a sample report at the canonical views to prove consistent numbers.
  6. 06Hand over the dictionary plus views as the required base for any future dashboard.

Stack

Tools and layers

  • Supabase Postgres
  • Canonical SQL definition views
  • Markdown KPI dictionary
  • Metabase (shared models)
  • Next.js 16 (consumes the views)
  • Inputs layer: Collect every KPI in use and capture how each is currently (mis)calculated across tools.
  • Transform layer: Run a definition session to agree numerator, denominator, window, and filters for each KPI.
  • Metrics layer: Supabase Postgres contributes the trusted model for KPI Definition Cleanup Before Any so metrics are defined before they are visualized.
  • Visualization layer: Canonical SQL definition views handles refresh, review, or reporting delivery while a short, deliberate cleanup that writes down each KPI's exact definition (numerator, denominator, window, filters) and implements it as a single ca...
  • Action layer: One agreed definition per KPI, written down; Canonical SQL views every later report reads from; Plain-language KPI dictionary owners can actually r...

Data flow

  1. 01Collect every KPI in use and capture how each is currently (mis)calculated across tools.
  2. 02Run a definition session to agree numerator, denominator, window, and filters for each KPI.
  3. 03Implement each agreed KPI as one canonical view so there is a single source for the number.
  4. 04Write a plain-language KPI dictionary so non-technical owners can read the definitions.
  5. 05Point a sample report at the canonical views to prove consistent numbers.
  6. 06Hand over the dictionary plus views as the required base for any future dashboard.

Controls

  • Two reports show different numbers for the same 'conversion rate' because nobody agreed what counts as a lead, a qualified lead, or a conversion —...
  • A short, deliberate cleanup that writes down each KPI's exact definition (numerator, denominator, window, filters) and implements it as a single ca...
  • When automation confidence is low, route the record to a manual owner with the source, stage, and last action attached.

Research basis