Skip to content

0022. A reef adds a screen to the portal as a Web Component its Nereid serves, named in its contract

In short

A reef adds a screen to the portal as a Web Component its Nereid serves, named in its contract, loaded at runtime. Status: Accepted (2026-11-08).

Status: Accepted (2026-11-08)

Context

The portal (spec 0008, #729) is a PWA with no build and no framework: static/index.html, app.js and app.css, served by the nereus-portal Nereid on port 8081. It forwards /v1/* to the Nereus API (ADR 0018, the one door) and sends a Content Security Policy of default-src 'self', connect-src 'self' <issuer origin> and frame-ancestors 'none'. Reefs and their Nereids extend the CLI with their own commands (ADR 0004), and reefs are installed at runtime (ADR 0010); the portal has no such extension point, and #46 asks that "a new Controller adds screens without a portal release".

The owner asked on 2026-11-06 "microfrontends? Module? How?" (#1102, Tide in the portal; this is its step 1, #1103). Tide, the idea timeline, is the first screen that belongs to a reef that is not the portal: the ideas reef. The tabs already planned as portal features (#740 status, #750 orders, #777 threads) show the platform's own state, not a reef's.

The Nereid's contract today is GET / on its controller port (8080, inside the cluster only), an object such as {"name": "nereus-portal", "commands": []}. Errors follow ADR 0012: what happened, the cause, how to check, how to fix, in one line per field.

Decision

A reef adds a screen to the portal as a Web Component its Nereid serves. The options weighed:

Option What it is Fits Against
Module of the portal One more tab in controllers/nereus-portal/static/ The fastest first slice Every capability needs a portal release; the portal grows to know every reef, the opposite of ADR 0004, ADR 0010 and #46
Microfrontend at runtime, Web Components The reef's Nereid serves an ES module that defines a custom element; its contract names it; the portal loads it when the reef is installed Mirrors ADR 0004 for the portal; no build and no framework, like the portal; same origin, so the CSP stays 'self' A small contract to design and keep stable
Module Federation Webpack or Rspack federated bundles Mature for big SPA teams Needs a build and a shared runtime; the portal has neither
single-spa A root config that mounts apps Framework-agnostic A second router and lifecycle on top of a 200-line app
iframe The Nereid serves a whole page, framed Strong isolation Breaks the PWA's theme, language and sign-in; frame-ancestors 'none' today
Backstage plugin The wasp-idp path (#30) Ecosystem A Backstage instance the portal does not have

The contract gains a screens list, versioned by a contractVersion field (an integer, 1 with this ADR; a Nereid with no contractVersion serves no screen). Each entry has exactly these fields; an unknown field makes the entry ignored, never half-loaded:

{
  "name": "doris",
  "commands": [],
  "contractVersion": 1,
  "screens": [
    {"tab": "Tide", "element": "nereus-tide", "module": "tide.js", "icon": "waves"}
  ],
  "assets": ["tide.css"],
  "uiPort": 8082
}
  • tab: the label of the tab. element: the custom element's tag name, which must start with nereus- and contain a hyphen. module: a file name of the Nereid's ui/ folder, no slash and no dot segment, ending in .js. icon: the name of an icon the portal already has, else a default.
  • The portal's Nereid reads the screens from each Nereid's status.screens (the SDK copies the contract's list there, so the cluster holds one list and the API reads what Nereids publish, ADR 0018), and the portal asks the API for them (GET /v1/screens, built in #1105). A tab shows only while its reef is installed.

The portal's Nereid forwards /reefs/<reef>/ui/<file>, not the API (the open point of #1103, decided as recommended). The forward serves static files only, from an allow-list built from the contracts: GET only, a file that some screens entry names (module) or that sits in the Nereid's ui/ folder and is listed by the same contract in assets (an optional list of file names, such as a stylesheet or an icon), no query, no dot segment, backslash or percent-encoded slash (the check /v1 already has). It forwards to the reef's Nereid on its controller port, GET /ui/<file>, which answers only files it listed in the contract; anything else is 404. A Nereid may serve ui/ on a port of its own instead, named by the contract's optional uiPort (an integer from 1024 to 65535, copied to its status like screens; #1108), so a NetworkPolicy opens that port to the portal's pods without opening the Nereid's data, since it holds a port, not a path; the forward then targets that port. Same origin, so the CSP stays 'self' and no header is relaxed. The API does not carry code: it carries data.

The element's interface. The portal creates the element with document.createElement(element) after import("/reefs/<reef>/ui/<module>") and sets, as properties and never as globals:

  • api: an object with get(path), post(path, body) and delete(path), each a fetch bound to /v1 with the person's token; the token itself is never given. A path outside /v1 is refused.
  • lang: pt-BR or en, set again when the person switches the language.
  • The theme as CSS custom properties the portal defines on :root (--nereus-bg, --nereus-fg, --nereus-muted, --nereus-accent, --nereus-border, --nereus-radius, --nereus-font), which cross the shadow boundary; the palette follows prefers-color-scheme as the portal's does.
  • The element owns its shadow DOM (mode open) and its styles; the portal's CSS does not reach it.
  • The element reads and writes data only through /v1 (ADR 0018), never from the screen to the Nereid directly: connect-src has no other origin, so the browser enforces it.
  • It dispatches nereus-error (a CustomEvent whose detail has the ADR 0012 fields message, cause, check and fix) when it cannot work, and the portal shows that line in the tab. It sets no title, route or history of its own.
  • It may dispatch nereus-focus (a CustomEvent whose detail.focused is true or false) when it shows one item and when it goes back to its list (#1761): while focused, the portal hides its mark, its language switch and its tab bar, and the screen takes the whole view, as a phone app hides its tabs inside a detail.
  • It may dispatch nereus-signin (a CustomEvent whose detail.resume is a small JSON value, at most 1 KB) when a call still answers 401 after the portal's renewal, the sign-in having ended (#1910): the portal signs in again by a full redirect and, back, opens that screen at once and sets its resume property to that value before api, so the screen reopens where it was.

When a module fails to load (a 404, a syntax error, a customElements.define that throws, the element never defined within 10 seconds, or a nereus-error), the tab shows the error line of ADR 0012, with the reef and the file named, and the rest of the portal keeps working. The portal never retries on its own; the person reloads the tab.

The portal's built-in tabs (#740, #750, #777) stay modules of the portal: they are the platform's own, not a reef's, and need no contract.

Tide is the first consumer: the ideas reef's Nereid doris serves tide.js, which defines <nereus-tide>, and reads its notes from GET /v1/ideas/notes (#1107). It proves the extension point against a real screen, not an abstract one.

Prior art

  • Custom Elements and Shadow DOM (WHATWG HTML Standard, custom elements): the browser's own component model, with no library; the contract is one tag name and one module.
  • Backstage's frontend plugins (backstage.io): the portal loads a plugin's UI at runtime; Nereus keeps the idea and drops the build and the framework.
  • Module Federation (module-federation.io) and single-spa (single-spa.js.org): the microfrontend patterns weighed above; the pattern is the same (an independent team ships a screen), the mechanism here is the platform's.
  • Micro Frontends (micro-frontends.org, Cam Jackson on martinfowler.com): the case for Web Components as the integration contract between a shell and its parts.

Consequences

  • The same contract carries a reef's MCP tools (ADR 0029, a tools list read with contractVersion 2), served by the Nereus API at /mcp.
  • A reef adds a screen with no portal release: install the reef and its Nereid, and the tab appears.
  • The Nereid SDK and templates/nereid learn the screens, assets and contractVersion fields and serve ui/ (#1105 builds the portal's side and the SDK's).
  • The portal's Nereid gains a read of the Nereids' status and a forward to another Nereid's controller port; its admission policy and Role change in the same issue. A screens entry cannot make the portal fetch anything outside the allow-list.
  • A reef's screen runs code in the portal's origin, with the person's token reachable through api. Installing a reef is therefore trusting its code as the portal's own (OWASP A08); the allow-list and the 'self' CSP limit where it can reach, not what it does with the data it may read. A signed module is a later decision.
  • The contract is versioned: a change that breaks an element's interface raises contractVersion, and the portal loads only the versions it knows, with the ADR 0012 line for the others.
  • Until v1.0.0 this ADR is rewritten in place when the decision changes (ADR 0001).

Origin

Decided as a recommendation on 2026-11-06 and 2026-11-08 in #1102 and #1103, from the owner's question about microfrontends; raw data in #pontos/raw/2026-11-06/ (Drive) for the voice session of that day.

Open questions

  • Signing the modules a Nereid serves, so the portal loads only code a Mandate approved.
  • Whether a screen may offer a command to the CLI as well, as ADR 0004 does for commands.
  • Isolating a reef's screen from the portal's origin (a sandboxed iframe or an origin of its own, with a narrow API over postMessage), so its code cannot reach the person's token; until then the portal keeps the browser's own fetch before any reef module loads, and its forward follows no redirect and sets each file's type from its extension (#1105).