Architecture¶

portalr's design is lattice RFC-0002, and its plan RFC-0001. Its decisions are in adr/. This page describes what exists.

The parts¶

The router¶

An application mounts portalr_router(resolve_actor=, grants=, readers=, invite=, site=, people=) at /portalr (ADR-0011). grants is grantr's Grants, with portalr's catalog, portalr.actions.ACTIONS, among its catalogs: grantr's roles give a tenant's owners and admins its reads, and operators the deployment's.

Each read names its tenant with X-Tenant. Each answers ok, unavailable or unconfigured, so a tool that is down fails only its own read. A refused request answers 400, 401, 403 or 422 with a Refused body, as artifactr's and reflexr's routers do: lattice-core's, from which refusals builds the four statuses it documents (lattice ADR-0021). schemas/portalr.openapi.json is the routes' document, and a test holds it to the router.

The readers¶

Each reader takes a Tenant and typed parameters, and builds its query with the tenant first:

tests/readers/test_queries.py builds every query each reader can send, and fails if one lacks its tenant.

The acceptance tests¶

moon run portalr:api starts a test application, tests/app/, beside Tempo, Loki, Prometheus and prom-label-proxy, from compose.yaml and stackr's configuration (ADR-0012). Then:

1. tests/acceptance/ seeds two tenants' traces, logs and metrics, one trace shared between them, and reads as each, through the readers and raw through prom-label-proxy: neither sees the other's;
2. the Bruno collection's up/ reads every route, and checks the refusals;
3. Tempo, Loki and the proxy stop, and down/ finds each read unavailable;
4. Schemathesis runs over schemas/portalr.openapi.json.

Langfuse and LiteLLM aren't in that stack, so their reads answer unavailable there; contract tests cover them, and stackr's Smoke job reads both up through scripts/smoke_readers.py.

The app¶

web/app is the people's UI, at /portalr/app/. It reads config.json first, signs in through Supabase Auth's client, @supabase/auth-js, and asks the server through client's queries, each carrying the current token and the tenant its route names (ADR-0014). Commands go over each library's stream, except a stored rule's, which goes over reflexr's REST, for an answer to every one; and each live event on a workspace's streams makes stale the reads it changed (ADR-0020). What a workspace's runs filed in its tracker is read from relayr's own route, where config.json's surfaces.relayr names one, and its runs' chains and the tracker: events that fired them come from reflexr's stream (ADR-0047). A workspace's integrations are read once as it opens, from grantr, and kept: they say which of Markdown's add-ons it may draw, each is its registry default where they can't be read, and a command artifactr refuses as not_enabled reads them again (ADR-0045).

TanStack Router's route tree, src/routeTree.gen.ts, is committed, and a test holds it to src/routes/. moon run app:bdd runs one feature per area through playwright-bdd, in Bun, against the test application with Supabase Auth (GoTrue, alone) in compose's bdd profile, served at /auth/v1 on its origin (ADR-0013). The native files' scenarios check files out to the hosted editor, a stand-in for WordCraft's build that compose's editor profile serves on a port of its own, which the script starts first and names to the application (ADR-0050).

The chat¶

ui's chat renders what client's artifactr store holds, and hands each command to its caller (ADR-0015):

ui imports client's types alone, which a root test holds it to. Markdown and a dashboard are held to the UIs' Content-Security-Policy too: ui's csp tests build a page of them as the UIs are built, serve it with the policy a portalr test holds to the router's, draw each from the page's own task, and fail on any violation in Chromium (ADR-0043, ADR-0047).

A dashboard's panels are plain JSON, with nothing in them that runs, and each is drawn by a registry of renderers keyed by its type, PANELS by default: StatCard, Markdown, and the dashboards add-on, loaded on demand while ui:dashboards is on, which holds the kit's charts and a table panel's sorting, filtering and pages on TanStack Table. Another drawing of charts or tables replaces a renderer there, and neither the panels' format nor the artifact's schema changes; each chart's figures are built from its panel, whatever draws it, and are open where the add-on is off or won't load (ADR-0047).

Forms, dashboards and mini apps are switched on and off per workspace by an integration's key, ui:forms, ui:dashboards and ui:mini-apps, as Markdown's add-ons are by markdown:math and markdown:mermaid, which every part asks through one seam, IntegrationsContext, an isEnabled(key) over the registry's keys. The app gives it a workspace's integrations through client's useEnabled, so each is its registry default until they are read and where they can't be; a page with no read, as admin, has the same defaults, which ui writes once and a test holds to the registry (ADR-0045, ADR-0047). A key that is off degrades to read-only, said as "Not available in this workspace": a form keeps its fields, disabled, says which is off, and has no button; a dashboard still shows its snapshot, and its forms can't be sent; an app is its label and summary, as always in phase 1. With dashboards off, a chart isn't drawn and its figures are open. A command the server refuses as not_enabled, which names the integration, degrades the same way, at once, and makes the app read the workspace's integrations again; once that read says the integration is on, the form can be sent again.

admin¶

web/admin is the UI for a tenant's owners and admins and the deployment's operators, at /portalr/admin/, on the app's session (ADR-0023). The session, where each UI opens, allowedIn and useMe are client's; signing in, the account and the tenant switch are ui's.

moon run admin:bdd runs admin's features against the test application, which sends its telemetry through stackr's Collector to Tempo, Loki and Prometheus, with Langfuse and LiteLLM unconfigured.

The kit's look¶

ui's tokens are lattice ADR-0014's, with --edge, --wash, --accent-hover and --scrim beside them (ADR-0019), and --danger, for destructive actions alone (ADR-0021), each pair's contrast asserted in both schemes. Its typefaces, Schibsted Grotesk and Fragment Mono, are served from the UIs' own origin. The frame and its parts:

gallery.screenshot.test.tsx pins how they sit together, wide and narrow, in each scheme. It runs in CI alone, against Linux baselines.

Every area of a workspace renders in AppShell. The screens outside one are ui's Plain page: choosing a tenant or a workspace, with the account, and what went wrong, without it. Signing in is a card of its own. admin renders its frame, with its own mark.

The wheel¶

Vite builds app and admin into src/portalr/static/, which git ignores and the wheel carries. portalr's build depends on theirs, and ui-in-wheel, in check and the release workflow, fails unless this version's wheel holds both, each with its typefaces, and the typefaces' licences, and each UI's third-party notices (ADR-0033): the licences of the packages its bundle holds, written by its build, which fails on one the policy in web/notices/policy.json doesn't allow.