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 }
}
}
}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, withcompare previous period(orcompare baseline firmware == "1.3.0"), itstarget, and asparkline. 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,bythe dimensions (a time with its grain:by at week),splitinto series. Afunnelwith nobytakes its steps from its metrics, in the order written:funnel written, tested, proved.table: a dataset'srows, or metricsgrouped by dimensions andpivoted across columns;sort,page,export csv. A table grouped by several fields shows each of them, then the metrics.filters: adaterange, aselectof a dimension's values, asearch. 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 lightor--theme darksets the colours. Without it, a data app takes thethemeitsuiwrites, else the page's (the system's, or VS Code's).--png shots.pngtakes a picture of the screens by headless Chrome, after the charts are drawn.--screen Overviewkeeps one screen.--serveserves the page onhttp://localhost:8040/(--portto change it). The rows are sent again each time one of their files changes. Afrom livedataset reads.arche/live.json, whicharchec liverewrites, 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 }
}
}
}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
mapand afloorplantake their places from a dimension; the drawing they are laid on is not in the model yet. from budgetsreads 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 livedataset 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 acompareshows.