Core architecture contract

F21.00 0 features

At a glance

The architectural contract that pins every immutable decision about the sys console: hostname, deploy pipeline, identity providers, role matrix, session ceilings, audit posture, and the absolute ban on backdoors. Any pull request that contradicts a row here must update the contract first.

How it works

The contract lives as a single one-screen table that every engineer reads before touching the console. It locks the codename to `sys`, the host to `sys.petanque.life`, the monorepo folder to `sys/`, and the Static Web App to `swa-petanque-sys` inside the shared `rg-craft-easy` resource group. The deploy workflow `deploy-sys.yml` triggers only on `sys/**` and `packages/shared/**` paths and includes a design-drift gate so the console cannot ship visual regressions.

The frontend reuses the React Native + Expo desktop-first baseline already proven by `admin/`. There is intentionally no separate `sys-api`: every new endpoint is mounted on the shared `petanque-api` Container App under `/auth/sys/*` and `/sys/*`, and every existing endpoint that sys touches gains a `sys_*` capability check. Identity is OAuth-only via Microsoft or Google, scrubbed against the `SYS_ADMIN_EMAILS` allowlist, and finalised by a mandatory WebAuthn assertion before a sys-JWT is minted.

Sessions slide on activity for 60 minutes but never exceed an 8-hour hard ceiling per login, and a fresh-auth gate forces re-authentication within five minutes for anything destructive. Roles are split into `sys_support`, `sys_engineer`, `sys_finance`, and `sys_security`, each enforced server-side by the existing ACC-003 deny-by-default capability framework. Impersonation tokens carry `actor_id`, `sub`, and `impersonation_id`, with credential, money, legal-acceptance, and role-grant writes blocked at the middleware layer regardless of capability.

Every action lands in `sys_audit_entries`, append-only, WORM-sealed after 24 hours and retained for seven years. Crucially, sys runs the same code path as everyone else with an elevated capability set: no direct Cosmos access, no validation bypass, no hidden hooks.

Key capabilities

Locks deploy topology: SWA `swa-petanque-sys`, workflow `deploy-sys.yml`, shared `rg-craft-easy`
Pins identity model: Microsoft/Google OAuth + allowlist + mandatory WebAuthn second factor
Defines four sys roles enforced through ACC-003 deny-by-default capability matrix
Sets 60-minute sliding session with 8-hour hard ceiling and 5-minute fresh-auth gate
Mandates `sys_audit_entries` WORM-sealed at 24 hours, 7-year retention, trace-tagged per action
Forbids sys-only backdoors: same code path as tenant users with elevated capabilities only
Requires design-drift screenshot diff against `/design` in every console PR

In practice

A new engineer joins the platform team and is told to add a sys-only refund endpoint. Before reading 370 lines of feature specs they open the architecture contract and confirm the shape: no separate API, mount under `/sys/billing/refund`, gate with `sys_finance`, wrap in `@requires_fresh_auth(300)`, write `sys_audit_entries`, and route the UI under `sys/app/(dashboard)/billing/`. They notice that any inline hex colour or ad-hoc `fontFamily` will fail the design gate, so they import tokens from `packages/shared/src/design`.

When the PR opens, the deploy-sys workflow runs the visual-regression baselines and the audit-decorator lint. The contract has paid for itself: zero clarifying questions, zero ad-hoc shortcuts, and the change ships behind the same guardrails as every other sys feature.