App dashboards

The file names what to show and where the data comes from. Each panel reads, or for a form calls, one route the app's own version declares, and maps the route's answer with JSON pointers. The console calls those routes with route.call as the account viewing it, so the route's own gate decides every answer: the platform scopes the call, and the app never decides access in the dashboard. The platform checks the file once, when the version is checked or pushed, and keeps its canonical bytes; the console reads them with dashboard.get. Nothing is added to an app's request path.

Declaring it

Name the file in substrio.toml, beside plans_file:

dashboard_file = "dashboard.json"

substrio push carries it in the version it makes (the version member dashboard); a version made over the API carries it the same way (version.create's dashboard, an object). In the version's tree it is config/dashboard.json, so an agent that edits and commits the tree's files changes it the same way.

The dashboard is part of the version. It goes live with the version, in a sandbox on push and in the app on promote, and a rollback brings the older one back. A version without a dashboard leaves the app with none.

The file

{"nav": [
  {"id": "overview", "title": "Overview", "icon": "overview",
   "panels": [
     {"kind": "metric", "title": "Sent today", "source": {"route": "GET /stats"},
      "value": "/today", "cap": "/limit", "format": "number"},
     {"kind": "usage"}]}
]}

nav is the app's pages, in the order the console lists them. Each nav item is:

Pages that take params

A page whose panels read a route with :params (GET /orders/:id) is a detail page. The check derives its params (here ["id"]) and writes them on the nav item. The console does not list such a page in the menu; a table's drill-down opens it with the params bound from the clicked row. Every drill-down to it must bind exactly those params.

Panels

Every panel has a kind. title (1 to 128 bytes) is required for the five kinds that read a route and optional for the others. A field that is not one of its kind's is refused.

Fields every kind takes, and the ones the reading kinds take:

source is {"route": "METHOD /path"}: a method of GET, POST, PUT, PATCH or DELETE, one space, and the path exactly as a function of the same version declares it (its parameters by the same names, GET /orders/:id). The route's gate and ip words are left out: "GET /stats" names the route declared as "GET /stats auth". A route declared with no method, or as ANY, answers every method on its path.

A table's columns and a record's fields are each {"field", "label", "format"}: field a pointer into the row (or the record), label 1 to 128 bytes, format optional (text). A form's fields are each {"name", "label", "type", "options"}: name the body member it sets (1 to 64 letters, digits, _, -, unique in the form), label, type optional (text), and options (1 to 64 strings) for a select and only a select.

A module panel names the module by its id (1 to 64 letters, digits, _, -): {"kind": "module", "module": "domains"}. Modules are the featured apps' own console code; any other app's module panel is refused.

Paging

A table with cursor (a pointer to the next page's cursor in the answer, "/next") pages: the console calls the route again with ?cursor=<that value>, until the answer holds none. No filter of a paging table may be called cursor.

Filters

Each filter of query is {"name", "label", "type", "options"}: name the query key (1 to 64 letters, digits, _, -, unique in the panel), label 1 to 128 bytes, type one of:

A filter left empty is not passed. The route reads its query and answers what it should; the dashboard never filters an answer itself.

Actions

A table (on each row) and a record may have actions, 1 to 8 buttons:

{"id": "refund", "label": "Refund", "route": "POST /orders/:id/refund", "params": {"id": "/id"},
 "confirm": "Refund this order in full?", "danger": true, "role": "admin"}

Every :param of an action's route is bound by its params or by its page's params (a record on a detail page binds :id from the page). One that neither binds is refused.

A form's submit is an action too: its button. It is the label alone ("submit": "Send") or {"label", "confirm", "danger", "role"}, and it calls the form's own source route.

Drill-down

A table may have open: {"item": "<nav id>", "params": {"id": "/id"}}. Clicking a row opens that nav item with the params bound from the row into its panels' routes (GET /orders/:id). item must be a nav item of the file, and params must bind exactly the params that page takes, no more, no fewer.

Who sees what

role on a nav item (default member) and on an action (default admin) says the least role of the viewer's account that sees it: owner above admin above member. The console hides what the viewer's role cannot use. That is presentation only: the call itself is route.call as the viewer, and the route's gate decides it. Give a destructive route a gate that refuses who should not use it; never rely on role alone.

Pointers

Every mapping is a JSON pointer (RFC 6901) into the route's answer: "" is the whole answer, "/today" its today member, "/days/0/count" the first day's count. In a pointer, ~1 is a / inside a name and ~0 a ~; any other ~ is refused. At most 256 bytes.

Formats

Form inputs: text, number, email, select, toggle.

Limits

A file past any limit is refused whole, naming the path.

When it is checked

version.check and version.create check the dashboard before anything is stored: every field, every limit, every source, action and badge route against the routes of that same version, every :param bound, every drill-down's nav item and params, and a module panel against the app being featured. A refusal is DASHBOARD_INVALID with field naming the path, so an agent sees it before it ships. A version whose dashboard is refused is not stored; what is live stays as it was.

The checked file is written back canonical: fixed key order, compact, every default written ("format": "text", "width": "full", "refresh_seconds": 0 on the kinds that refresh, "role" on every nav item and action, "danger": false, a submit as its object), a page's derived params, bindings sorted by name. Absent optional parts (cap, cursor, open, badge, confirm, query, actions) stay absent. Those bytes are what the version carries and what dashboard.get answers, whatever the file's own key order and spacing. Nothing is parsed again after the check.

To see a version's dashboard as the console will draw it before it goes live, read dashboard.get with that version (?version=<number or id>, below): every nav item and panel, checked against that version's own routes by the same checker, canonical. version.check answers only whether the file passes.

Reading it: dashboard.get

GET /v1/_accounts/{id}/apps/{slug}/dashboard (MCP substrio_dashboard_get {id, slug}, substrio dashboard get id=7 slug=shop, the SDK from the same operation) answers the app's stored dashboard, the canonical bytes, as they are. An app with none answers {"nav":[]}. The live version's dashboard is the stored one: promoting a version stores its dashboard, and a version without one removes it.

{id} is the account the caller reads through, and the app is read when:

• the account holds the app (the caller is a member signed in, or one of the account's keys);
• the app is a featured app the account has enabled (featured.enable).

A caller who is not in the account is answered 404 ACCOUNT_NOT_FOUND. Any other app is answered 404 TENANT_NOT_FOUND, the same as an app that does not exist, so a dashboard never tells an outsider an app is there.

curl -H "Authorization: Bearer $TOKEN" https://substrio.com/v1/_accounts/7/apps/shop/dashboard
# {"nav":[{"id":"home","title":"Home","icon":"overview","panels":[{"kind":"usage"}]}]}

Cost: the caller's standing in the account (1 lookup), 1 app snapshot, 1 database lease, 1 record read and 1 copy into the reply; 0 parses. For a featured app read by another account, +3 flag tests and +1 read of the account's plan record there.

One version's dashboard: version

GET /v1/_accounts/{id}/apps/{slug}/dashboard?version=12 (MCP substrio_dashboard_get {id, slug, version}) answers the dashboard of version 12 instead of the live one: checked against the routes that version's own functions declare, by the same checker a push runs, and written canonical. A version without a dashboard answers {"nav":[]}. version is a number or an id (64 hex digits); a branch, live or a sandbox's name works too, as in version.check. Use it after a push and before a promote to see exactly what the console will draw.

curl -H "Authorization: Bearer $TOKEN" "https://substrio.com/v1/_accounts/7/apps/shop/dashboard?version=12"

A version's history is its own account's: version on a featured app read by another account is refused with INVALID_ARGUMENT, field version. Cost, paid only when version is named: 0 reads for a number (any other name 1 ref read and 1 version read), 1 manifest read, 1 parse; no database lease.

Refusals

The details, as the server writes them:

A worked example: an orders app

The app's functions declare GET /orders/count auth ({"open", "revenue", "refunded"}), GET /orders auth (one page of {"items", "next"}, reading q, status, placed_from, placed_to and cursor), GET /orders/:id auth, POST /orders/:id/refund auth:ADMIN and POST /orders/:id/notes auth. Its dashboard.json:

{"nav": [
  {"id": "orders", "title": "Orders", "icon": "card", "badge": {"route": "GET /orders/count", "value": "/open"},
   "panels": [
     {"kind": "metric", "title": "Open", "width": "third", "refresh_seconds": 30,
      "source": {"route": "GET /orders/count"}, "value": "/open", "format": "number"},
     {"kind": "metric", "title": "Revenue", "width": "third",
      "source": {"route": "GET /orders/count"}, "value": "/revenue", "format": "money"},
     {"kind": "metric", "title": "Refunded", "width": "third",
      "source": {"route": "GET /orders/count"}, "value": "/refunded", "format": "money"},
     {"kind": "table", "title": "Orders", "source": {"route": "GET /orders"}, "rows": "/items", "cursor": "/next",
      "query": [{"name": "q", "label": "Search"},
                {"name": "status", "label": "Status", "type": "select", "options": ["open", "paid", "refunded"]},
                {"name": "placed", "label": "Placed", "type": "date_range"}],
      "columns": [{"field": "/id", "label": "Order"},
                  {"field": "/total", "label": "Total", "format": "money"},
                  {"field": "/status", "label": "Status", "format": "status"}],
      "open": {"item": "order", "params": {"id": "/id"}},
      "actions": [{"id": "refund", "label": "Refund", "route": "POST /orders/:id/refund", "params": {"id": "/id"},
                   "confirm": "Refund this order in full?", "danger": true}]}]},
  {"id": "order", "title": "Order", "icon": "file",
   "panels": [
     {"kind": "record", "title": "Order", "source": {"route": "GET /orders/:id"},
      "fields": [{"field": "/id", "label": "Order"},
                 {"field": "/total", "label": "Total", "format": "money"},
                 {"field": "/placed_at", "label": "Placed", "format": "date"}],
      "actions": [{"id": "refund", "label": "Refund", "route": "POST /orders/:id/refund", "danger": true,
                   "confirm": "Refund this order in full?", "role": "owner"}]},
     {"kind": "form", "title": "Add a note", "source": {"route": "POST /orders/:id/notes"},
      "fields": [{"name": "text", "label": "Note"}], "submit": "Add"}]}
]}

What the console shows an owner: an Orders entry in the app's menu with the open count beside it. The page opens on a row of three meters, Open (re-read every 30 seconds), Revenue and Refunded, over a full-width table of orders with a search box, a status picker and a date range. The table pages with a "More" control while the answer has a next. Each row has a red Refund button that asks "Refund this order in full?" and then calls POST /orders/o_42/refund as the owner. Clicking a row opens the Order page, which is not in the menu since it takes :id, bound from the row's /id. That page has the order's fields, an owner-only Refund (its :id bound from the page), and an "Add a note" form that posts {"text": "..."} to POST /orders/o_42/notes.

Pushing it with "route": "POST /orders/:id/cancel" on the table's action, a route no function declares, is refused before anything is stored:

{"code": "DASHBOARD_INVALID", "next_action": "correct_request", "field": "nav[0].panels[3].actions[0].route",
 "detail": "nav[0].panels[3].actions[0].route names no route this version declares: POST /orders/:id/cancel", "...": "..."}