The MMS application: a Remix web app, a PostgreSQL/PostgREST data plane, and the architecture and delivery roadmap defined in the MMS Unified Implementation Plan.
The implementation roadmap is structured into modular parts: target architecture & auth foundation (docs/plans/auth-implementation-plan.md), rectification phases R0–R10 (docs/plans/rectification-implementation-plan.md), native acceptance environment (docs/plans/r8-6-implementation-plan.md), review baseline evidence (docs/plans/review-baseline.md), and execution status & decisions (docs/plans/rectification-decisions.md). Trusted-proxy rules are in docs/runbooks/request-context.md. For a full index of system documentation, see docs/README.md.
Versions are pinned, not ranged:
| Component | Pin | Declared in |
|---|---|---|
| Node.js | ^24.7.0 |
root and apps/web engines, .tool-versions, CI |
| Remix | 3.2.0 (exact) |
apps/web/package.json (see ADR-0002) |
| TypeScript | 7.0.2 (exact) |
apps/web, packages/* devDependencies |
@types/node |
26.6.6 (exact) |
apps/web devDependencies |
| PostgreSQL | 18.6 |
infra/compose.yaml, .tool-versions |
| PostgREST | 16.5 |
infra/compose.yaml, .tool-versions |
| pgschema | 1.13.4 (checksum-verified in CI) |
.tool-versions, CI |
R8.3 of the rectification plan required removing the floating latest ranges; a
regression test (apps/web/app/version-pins.test.ts) fails if a toolchain
dependency is declared as latest, * or a range again. Local development on a
newer Node (for example 26.x) works, but CI and the pin describe the supported
line.
apps/web/— the Remix app and the only deployable workspace.app/routes.tsgroups the URL contract by owning controller;app/actions/*/controller.tsxserve their group.- Root controller at
app/actions/controller.tsxserves only/assetsand the JWKS document. - Groups:
session/,identity/,auth/,mfa/,break-glass/,admin/(withproposals/,external-users/),uploads/,survey/,triage/. - Shared action helpers live in
app/actions/helpers.tsx. app/actions/home-page.tsxandapp/actions/document.tsxrender the starter UI.app/actions/public/contains the browser runtime entry and interactive prompt button.app/routes.tsdefines the shared route contract used by server and browser modules for type-safe hrefs.app/router.tswires routes to handlers and installs the standard Remix component renderer used by actions.app/assets.tsowns the server-side asset pipeline used by the asset route and render middleware.server.tsandhmr.tsare the runtime entries;public/holds static files.
packages/— framework-agnostic libraries (domain,pgrst-client,test-utilsas they are added).db/— declarative schema, bootstrap, migrations, seeds and database scripts.infra/— local compose and deployment assets.docs/— ADRs, architecture, security notes, runbooks, and implementation plans (see docs/README.md and docs/plans/README.md).
npm i
npm run dev
npm run hmr
npm run start
npm test
npm run typecheck
npm run check
npm run doctornpm run hmr is for live server and browser updates; npm run dev only watches and restarts the server. npm run check runs the workspace typecheck and tests.
Every npm run db:* script spawns many short-lived psql processes — db:migrate starts one per migration plus one per seed file, and db:check builds two scratch databases and starts roughly a hundred. Each is a fresh libpq connection, so if PostgreSQL asks for a password and none is available, you get one prompt per process.
Configuration can be supplied via environment variables or a local .env file (which is loaded automatically by repository scripts). Put credentials somewhere libpq can see them on every connection without hardcoding. Any one of these works:
# 1. In the URL. The scripts extract it, redact it in diagnostics, and set PGPASSWORD per call;
# the BFF/worker/sealer pools derive their URLs from DATABASE_URL and keep it too.
export DATABASE_URL='postgresql://postgres:YOUR_PASSWORD@127.0.0.1:5432/mms_dev'
# 2. As an env var, inherited by every psql/pg_dump/pg_restore subprocess.
export PGPASSWORD='YOUR_PASSWORD'
export DATABASE_URL='postgresql://postgres@127.0.0.1:5432/mms_dev'
# 3. In ~/.pgpass (mode 0600) — covers every libpq client, including direct psql.
# hostname:port:database:username:password
echo '127.0.0.1:5432:*:postgres:YOUR_PASSWORD' >> ~/.pgpass && chmod 600 ~/.pgpassFor purely local development instances, native local acceptance tests run against PostgreSQL with role passwords configured via .env or standard libpq credentials. Never use unredacted credentials or hardcoded universal passwords.
Native PostgreSQL 18.6 and native PostgREST 16.5 form the canonical R8.6 acceptance test environment. Docker Compose (infra/compose.yaml) is non-canonical and retained only for legacy or isolated disposable CI purposes. See docs/testing/native-environment.md.
npm run testenv:init -- --allow-initial-create # idempotent cluster, roles, & signing key setup
npm run testenv:check # verify native prerequisites and drift
npm run testenv:reset # reset and re-seed disposable acceptance database
npm run testenv:start # start native PostgREST daemon
npm run test:e2e # run integration and real Playwright browser testsnpm run dev starts the HTTP server on :44100 and, in development, every background scheduler: runtimePlan() defaults to all outside production, so server.ts starts the outbox poller, the Entra sync, the malware scanner and the break-glass drill checker. Those connect to PostgreSQL immediately. With no database listening on the default 127.0.0.1:55432 you get ECONNREFUSED from the poller every 5 seconds — the server itself is fine, it is only the schedulers complaining.
Full local setup, in order:
# 1. Point every client at your real PostgreSQL. The gateway/worker/sealer pools
# derive their URLs from DATABASE_URL by swapping only the username, so the host,
# port and password carry through. 55432 is only the repo's dev default.
export DATABASE_URL='postgresql://postgres:YOUR_PASSWORD@127.0.0.1:5432/mms_dev'
npm run db:bootstrap # creates roles, schemas, extensions (idempotent)
npm run db:migrate # applies migrations + seeds
npm run db:fixtures # organisation tree (idempotent, no users)
# 2. Bootstrap creates login roles without passwords. On a password-auth server,
# set them and export the matching URLs, or use local trust in pg_hba.conf:
# MMS_GATEWAY_DATABASE_URL, MMS_WORKER_DATABASE_URL, MMS_SEALER_DATABASE_URL
# 3. Signing key: every authenticated request mints an ES256 token, so the signer
# needs a key and PostgREST needs the matching public JWKS (see the rotation runbook).
export MMS_JWT_PRIVATE_KEY_FILE=/path/to/private.pem
export MMS_JWT_KID=dev
# 4. Start PostgREST on :3001, then the app (MMS_PGRST_URL defaults to that port).
npm run devTo look at the HTML shell without a database at all, run MMS_RUNTIME_ROLE=web npm run dev: that skips the schedulers and their connections, but any action that reaches the database will still fail.
The BFF signs ES256 (EC P-256) tokens. The native test environment manages signing keys centrally in .testdata/keys/ (mode 0700/0600, excluded from git). PostgREST verifies with the public half only, as a JWKS.
# Generate or verify acceptance signing keys in .testdata/keys/
npm run testenv:keys
# Or rotate keys on demand:
npm run testenv:keys -- --rotateOr manually using openssl and node:
# 1. Private key (PKCS#8). Keep it out of the repo; it is a signing credential.
mkdir -p .testdata/keys && chmod 700 .testdata/keys
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out .testdata/keys/mms-jwt-private.pem
chmod 600 .testdata/keys/mms-jwt-private.pem
# 2. Matching public JWKS for PostgREST's PGRST_JWT_SECRET.
node -e '
const { createPrivateKey, createPublicKey } = require("node:crypto");
const { readFileSync, writeFileSync } = require("node:fs");
const jwk = createPublicKey(createPrivateKey(readFileSync(".testdata/keys/mms-jwt-private.pem", "utf8")))
.export({ format: "jwk" });
delete jwk.d; delete jwk.k;
writeFileSync(".testdata/keys/mms-jwks.json", JSON.stringify({
keys: [{ ...jwk, kid: "dev", alg: "ES256", use: "sig" }]
}, null, 2));
'
# 3. Feed both sides the SAME kid, and keep aud/role claim in sync.
export MMS_JWT_PRIVATE_KEY_FILE=.testdata/keys/mms-jwt-private.pem
export MMS_JWT_KID=dev
# PostgREST:
# PGRST_JWT_SECRET=@.testdata/keys/mms-jwks.json
# PGRST_JWT_AUD=mms-api # matches the signer's AUDIENCE
# PGRST_JWT_ROLE_CLAIM_KEY='$.role' # matches the "role" claimkid must match on both sides or PostgREST rejects every token. The JWKS endpoint at
/.well-known/jwks.json serves the same public set (see
docs/runbooks/signing-key-rotation.md for rotation and the Key Vault variant). Never
commit either the private key or a real kid; /tmp paths above are for local dev only.
- Put an action in the controller that owns its route group:
apps/web/app/routes.tsandapps/web/app/actions/*/controller.tsxare two views of one contract, andcreateControllerrejects an action for a leaf its map does not own. - Add a new group by adding a nested map in
apps/web/app/routes.tsplus a matching kebab-case directory with acontroller.tsx, thenrouter.map(...)it inapps/web/app/router.ts. - Add directories like
apps/web/app/data/orapps/web/test/when the app actually needs them. - Move shared UI into
apps/web/app/ui/once more than one route needs it.