How-to guides › Build data apps

How-to guides

Data apps

A data app is a screen of numbers: KPIs, charts, filters and tables over the data arche-lang already writes. That is test runs and evidence, simulation traces, tries, timing analysis, live telemetry and files of your own. The data is declared in the model, as datasets and metrics. A ui shows them, and archec checks every name, unit and target. Each number keeps its lineage: the metric, the dataset, the file it came from, the model line, and the requirement it is held to.

The templates start a data app on sample rows: archec new my-app --kind data-app --template product-overview, and archec new --kind data-app --list lists them. This page is a first guide; every word is in the language reference and in the spec. archec explain data lists the checks. The example is examples/bench-console.

A first data app#

requirement REQ-PASS "Release pass rate" {
  text "A release candidate shall pass at least 95 % of its bench runs."
  limit 95
}

dataset Runs "Test runs" {
  from json "data/runs.jsonl"
  dimension case, board, firmware, status
  measure duration unit ms
  time at
}

metric runs "Runs" = count() in Runs
metric pass_rate "Pass rate" = count(status == pass) / count() unit % in Runs { target REQ-PASS }

component Console "Bench console" {
  ui {
    display web
    screen Overview "Overview" {
      filters { date last 30d; select board; search case }
      row {
        kpi pass "Pass rate" { value pass_rate; compare previous period; sparkline by at week }
        kpi count "Runs" { value runs; compare previous period }
      }
      chart trend "Pass rate by week" { line pass_rate by at week; split board; on select filter }
      chart fails "Fails" { heatmap count(status == fail) by case, firmware; on select drill Case(case) }
      table recent "Recent runs" { rows Runs; columns at, case, board, status; sort at desc; page 20; export csv }
    }
    screen Case "Case" {
      table boards "By board" { columns board, pass_rate; group board; pivot firmware }
      button back "Back" { on press back }
    }
  }
}
Diagram: Bench console
What archec draws from this code: Bench console

archec ui main.arche lists each element with what it asks: its metrics, its dataset, its dimensions and grain, its comparison, its target. archec ui main.arche --json gives the model a page draws.

Datasets#

A dataset says where its rows come from, and what its fields are.

from Rows
evidence test .arche/evidence/test.jsonl: one per record (subject, plan, case, verdict, place, at, requirements)
sim "run.json" archec sim --json: one per event (t, at, kind, part, msg, state, the payload's fields)
tries, tries verdicts .arche/tries/: one per try (its values as params.NAME), or one per verdict
analyze threads "timing.json" archec analyze --json: one per thread, with its load (its time over its period); or cores, buses, memory, chains
csv "file.csv", json "file.json" a file of your own: a line, or an object (JSON Lines too); archec status --json gives one per requirement
live archec live: one per requirement, chain, thread and container at each update
observe "spans.json" OTLP JSON traces: one per span
budgets the model itself: one per part a budget adds up (budget, on, part, top, name, value, unit, allowance, mode, copies), with the part's words (prop maturity = "quote")

dimension names what a chart groups and filters by. measure names the numbers a metric adds up, each with its unit. time names when a row is: ms since 1970, or an ISO 8601 date. A metric reads only these fields.

Metrics#

A metric is an expression of aggregations: count(), count(status == fail), sum(x), mean(x), min, max, median, p95(x) (any percentile), and distinct(x). It may use + - * /, numbers and other metrics. where keeps some rows. A ratio with unit % is given in percent. A target is a number, or the requirement whose limit the metric is held to.

A target knows which side of it is good. target <= 80 is a most, target >= 95 a least, and a plain target 95 is a least. A requirement's limit is a most when it says so (limit driver_temp <= 80degC) or when its text does ("below 80 °C", "at most", "shall not exceed"). It is a least for "at least" or "above". So a peak temperature of 79.3 °C meets "below 80 °C", and its kpi says Target ≤ 80 °C met.

A metric is named apart from the fields of its dataset. metric vout = mean(vout) says two things, so archec warns and suggests a name (vout_mean). Until then a chart, a kpi and a table of metrics read the metric, while a table of rows, a histogram and a where read the field.

A table's last line adds up what adds up: a count and a sum. A max column shows the highest value, and a min column the lowest. A mean, a percentile, a rate or a row's own value shows nothing there, since adding them up means nothing.

The elements#

  • kpi: a metric's number, with compare previous period (or compare baseline firmware == "1.3.0"), its target, and a sparkline. A baseline is named on the page: "Compare with the baseline firmware == "1.3.0"".
  • chart: one line says its kind and what it shows: line, area, bar, stacked-bar, pie, donut, scatter, heatmap, funnel, xmr, histogram, map, floorplan, sparkline. Then the metrics, by the dimensions (a time with its grain: by at week), split into series. A funnel with no by takes its steps from its metrics, in the order written: funnel written, tested, proved.
  • table: a dataset's rows, or metrics grouped by dimensions and pivoted across columns; sort, page, export csv. A table grouped by several fields shows each of them, then the metrics.
  • filters: a date range, a select of a dimension's values, a search. Each filters every element of the screen whose dataset has that field.

A bar or stacked-bar on a time writes it at its grain (Nov 3, W45), as a line does. With compare previous period, each bar has the period before beside it, lighter; a stacked bar has a dashed tick at the total before. The legend names it. A floorplan is coloured by a metric (a ramp) or by a dimension: floorplan state by bench, x, y, w, h. Then each word has a colour and the legend lists them. A status word (ok, pass, running; warning, busy; fail, error, down) takes its status colour. A date last 60d filter offers "Last 60 days" first; w is weeks, mo months, y years.

on select filter filters the screen's other elements by what the reader clicked. on select drill Case(case) opens screen Case filtered to it.

Seeing it run#

archec ui preview main.arche writes one page, screens.html, that runs the data app on its rows. The page carries the rows and the charts' code, so it opens from a file and loads nothing from the network. Each data screen has its filter bar, cross-filters, drills, View rows, Export CSV and Inspect. A drill goes to the screen it names, and that screen's back button comes back. The screen's other elements, such as a button that goes to another screen, are drawn under it.

  • --theme light or --theme dark sets the colours. Without it, a data app takes the theme its ui writes, else the page's (the system's, or VS Code's).
  • --png shots.png takes a picture of the screens by headless Chrome, after the charts are drawn. --screen Overview keeps one screen.
  • --serve serves the page on http://localhost:8040/ (--port to change it). The rows are sent again each time one of their files changes. A from live dataset reads .arche/live.json, which archec live rewrites, so its charts follow the running system.

The VS Code UI Preview shows the same page beside the editor. Inspect's main.arche:37 opens the model at that line. Export CSV asks where to save the file. The colours follow the editor's theme, and the charts are drawn again when a data file changes. The simulator's page (archec sim --html) and archec gen --target ui-web run the data app too. archec doc --html draws each data screen as a figure, with its filters as they start.

What a click becomes is the engine's input: a filter bar's value, a picked mark's dimensions (a time is its grain's span, a bin its range), a drill's arguments. A drill with no screen (on select drill) shows the same chart one grain finer, on the period picked.

Asking the data#

archec mcp gives an AI agent three tools over the same data. dataset_list says where each dataset's rows come from, its fields and how many rows it has now. metric_query asks a metric by dimensions, grain, filters and comparison, and answers the result a chart draws with each column's lineage. data_app_check runs the data checks alone. The Claude Code plugin's build-data-app skill uses them.

What a reader moves#

Some screens are used, not only read. These pieces sit in the screen's grid like a chart, and the page draws them:

Piece What the reader does
slider s "Setpoint" { param SETPOINT } moves a parameter a metric names; input types it, stepper steps it
scenarios plan "…" { columns energy, cost } sees the metrics at the parameters' written values and now; names and saves a scenario
review approve, reject by chain on a table of rows picks a decision for each row; Sign off saves them as a file once all have one
replay week "…" { date last 7d } plays the screen through the last seven days, or steps it; Live shows every row
ask q "…" { rows Telemetry; text "max temp by board, weekly" } types a question in words, read in the page with no AI
canvas c "…" { blocks Telemetry } adds, moves and removes charts; a click on one filters the others
canvas c "…" { dice Telemetry } rolls a metric, a dimension, a filter and a grain, and keeps some
canvas c "…" { links part, requirement in Trace; split status } sees a link per row, lit by its status
canvas c "…" { walk part in Parts; columns max(temp) } walks with the arrow keys into a place per value, which shows its numbers

A metric may name a parameter of the project as a number: metric energy = LOSS * (SETPOINT - mean(outside)) * count() unit kWh in Climate. Its unit is the one written. A story step shows a data screen with screen Overview, and archec story export draws it with its numbers. What a reader keeps (decisions, scenarios, blocks) stays in the browser. The checks are data-param, data-review and data-story. The templates use each piece.

On a device#

archec gen --target ui-lvgl and --target ui-slint draw a data app on a device screen:

Element On the device
kpi its number and unit, its change against the comparison, its target
line a point at each update, a series per metric, the target as a flat line
xmr the values, their mean and the natural process limits (mean ± 2.66 × the mean moving range)
bar the bars the device gives, at most 12
table the rows the device gives, as texts, at most its page (10 without one)

A device has no files: the evidence, the CSV or the trace a dataset reads on a PC are not on it. So the generated code has a data struct with a slot per element, and a hook of yours fills it at each update. In C that is ui_<id>_data_fill in ui_<id>_data.c, written once. In the Slint glue it is the <Id>Data struct (ui.borrow_mut().data.<element> = …).

A from live dataset is the device's own. Its rows there are the part's variables, one row at each update. A field named like a variable of the part (temp, motor.rpm) is that variable. So metric peak "Peak" = max(temp) in Telemetry on a part with var temp: float32 is worked out by the generated code as the updates come: count, sum, mean, min and max of one variable. In C nothing is left to fill. In Slint, live(temp, motor_rpm) takes one row.

dataset Telemetry "Telemetry" {
  from live
  measure temp unit degC
  time at
}
metric peak "Peak temperature" = max(temp) unit degC in Telemetry

component Panel {
  var temp: float32 = 20
  ui {
    display 480x320
    screen Main "Main" {
      kpi hot "Peak temperature" { value peak }
      chart temps "Temperature" { line peak by at minute }
    }
  }
}
Diagram: Panel
What archec draws from this code: Panel

Every other data element (an area, a pie, a heatmap, a pivot table, the filter bar) is a label in its place. The generator says so in a note for each, as it does for a split, a sparkline or an export a device leaves out. --target ui-qml draws no data element yet; it says so for each.

Limits#

  • The query engine is TypeScript, the same in node and in the page. It is fine for runs and traces, thousands of rows, not millions.
  • A piece is drawn by the page only: on a device it is a label in its place. A parameter moved in the page is not written back to the model.
  • A served page sends all the rows again when a file changes, not only the new ones.
  • A map and a floorplan take their places from a dimension; the drawing they are laid on is not in the model yet.
  • from budgets reads the budgets the check adds up, part by part. A mode's budget (operating-mode … { budget power 60W }) is not in its rows.
  • A bar on a time matches the period before by place: the first bar with the first bar of the period before. A missing day shifts the pairs after it.
  • On a device, a metric of a from live dataset is worked out only when it is one aggregation of one variable; the hook fills the others. A device keeps no earlier period, so the hook gives the value a compare shows.