Why a figure is defined once

Business intelligence tools such as Microsoft Power BI, Tableau, Looker, Metabase, Grafana, Domo, Qlik Sense and Klipfolio let a builder drag a field onto a chart and calculate a figure there. That freedom is their strength. It is also how two reports come to show different answers for the same week: each chart keeps its own copy of the formula, and the copies drift apart.

This module gives every role the numbers it decides with from one source. A dashboard panel names a metric that is registered in the data fabric, and the platform reads the figure from the registry. The panel cannot hold a typed number or a figure calculated on the screen. The result is that the screen, the emailed report and the alert all show the same number, and any number can be followed back to its definition and its data.

What the module covers

The module builds dashboards and panels on registered metrics and dimensions, shares them by role through the Role and Exposure Matrix, adds filters, drill-down and time comparison, sends scheduled reports, raises alerts that a person acknowledges, and shows where any number comes from. It also embeds the same views on the three surfaces: operator at the machine, supervisor on the floor and manager in the office.

MVP capabilities are the must-haves before a business can cancel its old tool with confidence. STD capabilities match what mainstream tools offer.

Two pitfalls to design out

Four standards the module applies

The tables and what they point at

Every table in the module starts with the standard columns that every spine table has: id, tenant_id, created_at, created_by, updated_at, updated_by, row_version, archived_at and ext. The module has no people table, role list or file store of its own. It points at core_person, core_job_role, core_org_unit, core_attachment and core_action_item.

Column reference

These are the columns your AI coding agent builds from. Required means not null; allowed values are check constraints, which the database tests on every row. A foreign key is a column whose value must match the id of a row in another table. jsonb is a column type that holds structured data written like {"site": "S1"}, which Postgres can search inside.

dash_dashboard

dash_dashboard_version

dash_panel

dash_dashboard_share

dash_report_schedule

dash_report_delivery

dash_alert_rule

dash_alert_event

The registry tables the dashboards read

The data fabric owns these. The course builds the five it needs, each with the standard columns and row-level security. Keep numerator, denominator and value as exact decimals (numeric), never floating point, so a rate adds up the same way every time.

A panel is a question, not a number

A panel row says which metric to ask for, how to slice it, how to draw it and over which period. It never says what the answer is.

{
  "dashboard": "line-1-operator",
  "title": "Scrap rate, last 7 days",
  "metric_key": "scrap_rate",
  "dimensions": { "filter": { "site": "S1", "line": "L1" } },
  "chart": "number",
  "default_period": "P7D",
  "target_metric_key": null,
  "seq": 1
}

Draft, publish, version

A builder edits a dashboard as a draft. Publishing writes the next row in dash_dashboard_version from the saved panels, sets published_version_id, and records a dash.dashboard.published event. Viewers read only the published version, so editing a panel changes nothing for them until the next publish. A published layout never changes: a change is a new version, and the older ones remain as the record of what readers saw.

The module publishes dash.dashboard.published, dash.alert.raised and dash.alert.acknowledged. It consumes fab.metric.version_published, so the owners of dashboards that use a metric are told when its meaning changes, and fab.quality.score_dropped. A metric's version is its row_version, and ISO 8601 ^[2] fixes how every date and period is written. A metric may carry a reference to a standard such as ISO 22400-2 in standard_ref ^[3].

Roles and surfaces

Roles are jobs, not names. Five are people; three are not and have credentials of their own, which you set in your host's environment settings and never paste into a chat or a file.

Two locks protect a dashboard. The first is sharing: a row in dash_dashboard_share names a job role, an org unit or a person, and a dashboard that is not shared with you never appears. The second is row-level security: every panel query runs with the reader's rights, so a reader gets only the rows of their site (a manager, every site). A dashboard can be shared with a person and still show them "no data" for rows they may not read.

The Postgres facts that decide how the access rights are written: an update or delete finds rows only through the role's read right, so a role that updates rows must also read them, and the changed row must still pass that read rule. An insert that returns its row needs the read right too. The rights written in the Role and Exposure Matrix must cover everything the later sessions ask a role to do, because the database rules are generated from it.

One read function

Every screen, report and alert reads a number through one database function, read_metric(code, from, to, filter, group_by). It runs with the caller's rights, so row-level security applies to every call. It keeps, for each day, dimension and metric, the row with the latest computed_at (a correction replaces a value without editing it), combines rows by the metric's aggregation, and returns the value, numerator, denominator, the number of days with data and days in the period, with the previous period and the metric's target and version. The browser never calculates.

How rows combine matters. A rate is 100 times the sum of the numerators divided by the sum of the denominators. It is never the average of averages.

Round once, at display, to one decimal place with exact halves going up, and compare the unrounded numbers. Totals, targets and variances are worked out before rounding.

No data, never zero

No value row for the filter and period means no data, with the reason. A stored 0 is shown as 0. If only some days have data, the panel says how many: "5 of 7 days". A filter that selects different members of the same dimension at once gives no data, because no row can be two members.

Periods, filters and comparisons

A period is written as an ISO 8601 duration or interval ^[1], and a time of day as a timestamp such as 2026-03-16T06:05:00Z ^[2]. Here P7D means the 7 whole days ending the day before the as-of date. With the as-of date 2026-03-16, the period is 2026-03-09/2026-03-15 and the previous period, the same length immediately before it, is 2026-03-02/2026-03-08. One clock function gives every date, so a test can say "today is 2026-03-16".

Filters (site, line, product, period) change the question a panel asks. They never change what a panel holds. A filter is intersected with the panel's own filter and with the reader's row-level scope. A target comes from the metric (its target, owner module and version), so the screen can show who owns the target and where it came from.

Drill and lineage

A number is a link. The first click shows the value rows behind it: period, dimension, numerator, denominator, when each was computed and the metric version it was computed on. The second shows the metric's definition page: code, definition, formula, standard reference, grain, direction, target with its owner module, status and version. The third shows the source: the entities the metric reads, linked to the owning module's screen where one exists.

When a metric's definition changes, the registry publishes fab.metric.version_published. The alert service finds every published layout that names the metric and gives each dashboard owner one action item. The published versions do not change; the lineage page shows value rows computed on the old version beside the current one.

Charts people can read

• Text alternative. Each chart has the same numbers available as a table, so a screen reader or a printed copy loses nothing (WCAG 1.1.1) ^[4].
• Contrast. Text is at least 4.5 to 1 against its background (1.4.3) ^[5], and chart lines and bars at least 3 to 1 (1.4.11).
• Not by colour alone. Above or below target is written as a word as well as shown in a colour (1.4.1).
• Keyboard. Filters, drill links and the table toggle work from the keyboard (2.1.1) ^[3].
• Consistent notation. Following IBCS ^[6], use the same look for actual on every chart and a different but consistent look for the previous period and for the target; keep the same scale on charts that are compared; show a variance as a difference.

Scheduled reports

A dash_report_schedule row holds a five-field cron, a format (PDF or CSV), a list of recipients and the filters that narrow every panel. The report is built with the same read function as the screens, so it shows the same numbers. Recipients are people, never typed email addresses, and each must be able to read the dashboard and all the rows the filters select: the save route refuses a recipient who could not see it.

Alerts

An alert rule watches one registered metric. A threshold rule fires when a day's value is greater than (gt) or less than (lt) the rule's value. An anomaly rule (outside_band) fires when the day is further from the mean of the previous 7 daily values than the rule's value times their standard deviation, which is a measure of how spread out the values are. With fewer than 7 previous values it does not fire and says "not enough history". A flat history makes the band zero wide, so write down the smallest band you will accept on real data.

The module's four measures

The module measures itself with four figures. The first three come from its own tables, so none is typed in. They are module self-measures, worked out from the module's own dash_ tables and not read through the metric read function; they are not registered metrics, because the metric job cannot read a dash_ table and a dashboard that measured itself through its own panels would be circular.

Retired BI seats is counted outside the dashboards. A seat count typed into a panel would break the rule this module teaches.

Replace the old tool

List the old tool's most-used reports, define each figure once in the registry, rebuild those reports as dashboards, and run both side by side for a period. Compare every number before cancelling any seat.

• Explain every difference. Typical causes: the old chart's own formula against the registered definition, the day boundary or time zone, a filter, rounding, the refresh time, and zero shown by the old tool where the source had no data. A figure where the platform says "no data" and the old tool says 0 is a finding about the old tool.
• Decide with the figure's owner. If the old formula is right, change the definition in the registry once, as the metric steward, never in a chart.
• Write a rollback plan first. Name who tells the readers, the date after which the old reports are no longer used for decisions, who keeps the old tool read only, and who decides to roll back.
• Cancel with the facts. Check the vendor's notice period and how long you can still export after cancelling. Write the saving against the Retired BI seats measure.