Skip to content

🧰 Crates & tooling

The platform is 8 Rust crates and 7 npm packages in one repository, consumed by every own app from its sibling clone: by path in Cargo.toml, by file: in package.json, and as the platform build context in Docker. Their versions stay 0.1.0; the release is PLATFORM_VERSION. Around them, shared-core's scripts develop, check, ship and roll out the fleet. As of platform 0.26.0 (2026-10-06).

🦀 What each piece does

RUST CRATES path dependencies, grouped by who uses them IN EVERY BACKEND the seven apps and RefApp platform-app bootstrap · pg pool · feature set platform-auth sessions · links · TOTP · lockouts platform-events SSE liveness · the change bus platform-http error envelope · cache · headers platform-mail SMTP · the account-link mail platform-sync /api/sync · collections · sharing ONLY WHERE NEEDED platform-files uploads · SHA-256 · sweeps used by cardbox kouizine tripwise refapp platform-http-client reqwest, timeouts required used by mediascope tripwise and the sidecars tmdb gmaps osrm platform-avatar the opt-in profile picture used by kouizine tripwise refapp NPM PACKAGES file: dependencies, grouped the same way IN EVERY FRONTEND the seven apps and RefApp @platform/api-core the one fetch · 401 · envelope @platform/auth-ui auth provider · guards · pages @platform/events online/offline · SSE streams @platform/offline service worker · blob store @platform/sync local store · outbox · rounds · dots @platform/users-ui the accounts administration ONLY WHERE NEEDED @platform/avatar-ui picture · JPEG XL · crop used by kouizine tripwise refapp @platform/scene sign-in scene · Motion · runtime used by cardbox lightflow mediascope pooping tripwise refapp TESTS ONLY @platform/e2e Playwright helpers used by <app>/e2e refapp/e2e conformance/browser
Each crate and package once, grouped by who uses it; the chips name the only users.
Crate What it owns Contract
platform-app tracing, the Postgres pool options, the serve/drain skeleton, the fleet's one feature set —
platform-avatar the opt-in profile picture: its three users columns, /api/users/me/avatar, another account's /api/users/{id}/avatar, its sweep avatar.md
platform-auth cookie sessions, activation links, argon2, TOTP MFA, lockouts, /api/auth + /api/mfa auth.md, users.md
platform-events the public liveness stream, SSE slots, the change bus events.md
platform-files streamed uploads (size cap, SHA-256, real type), atomic commit, serving, sweeps files.md
platform-http the {"error"} envelope, the cache tiers, the security headers and the CSP hashes errors.md, caching.md
platform-http-client the one outbound client: reqwest that cannot be built without its timeouts http-client.md
platform-mail SMTP: config, startup check, bounded sends, the account-link mail auth.md
platform-sync /api/sync, collections and their registry, the change stream, per-item sharing sync.md, shares.md
Package What it owns
@platform/api-core the one fetch: timeout, credentials, the 401 hook, the error envelope
@platform/auth-ui the auth provider, guards and hooks, with default pages an app may replace
@platform/avatar-ui the opt-in profile picture: its URL, the JPEG XL decode, the 512 px crop, the stock dialog
@platform/events the online/offline store and the SSE stream helpers
@platform/offline the service worker registration, the blob store, the login picture's cache
@platform/sync the local store over IndexedDB, the outbox, the sync runner, the two status dots
@platform/users-ui the accounts administration page and its hook
@platform/scene the sign-in scene's engine: Motion 14.3.0 through motion/mini, the only package an app takes it from, and the runtime every scene shares (platform 0.37.0)
@platform/e2e what every Playwright suite of the fleet is written with

The contracts live in the platform repo's contracts/. An app reads them, never the platform's source.

🧰 shared-core scripts

DEVELOP dev-nginx.psm1 local nginx (in each repo) run-local.ps1 a local stack (in each repo) CHECK fleet-check.ps1 every suite, one table nginx-check.ps1 nginx behaves as deployed fleet-lockfiles.ps1 one dependency set fleet-deploy-script.ps1 the copies stay identical fleet-npm.ps1 npm advisories and versions fleet-screens.ps1 every page at 365 · 800 · 1280 SHIP deploy.ps1 build · publish · push (each repo) wait-redeploy.ps1 until a commit runs fleet-version.ps1 local · pushed · running ORCHESTRATE start-rollout.ps1 a rollout in the background /fleet-rollout roll a release out /new-app a new app from RefApp
Dashed boxes are byte-identical copies kept in every repo; the rest run from shared-core.
Script What it does Main switches
fleet-check.ps1 starts the local stack of each app whose repo changed, runs the source, HTTP, browser, app e2e and nginx checks, prints one table and a section per failure -All, -Own, -Plan, -Apps, -Cloned, -Strict, -Direct
nginx-check.ps1 proves the local nginx behaves as deployed: TLS, headers once, body caps, rate limits, SSE, WebSockets, the maintenance page -App, -NoMaintenance
fleet-lockfiles.ps1 the 12 lockfiles' version, profile and feature drift; -Update refreshes and gates them -Update, -Commit, -SkipPlatformCommit
fleet-npm.ps1 per app, npm advisories by severity, outdated packages and the shared stack's versions; refreshes them within or past their ranges, gated -Update, -Upgrade, -Commit, -Apps
fleet-deploy-script.ps1 each repo's deploy.ps1, run-local.ps1 and dev-nginx.psm1 against its canonical copy, and the tree's cargo config -Update, -Diff, -Script
fleet-version.ps1 per app: local HEAD, pushed, and what production runs, with its platform release -Apps, -NoFetch
fleet-screens.ps1 starts each app's local stack, shoots every page, menu and dialog at 365, 800 and 1280 px with overflow and tap-target checks, builds a gallery -Own, -Apps, -Only, -Widths, -Gallery
wait-redeploy.ps1 waits until /api/version names a commit -Url, -Commit
start-rollout.ps1 starts /fleet-rollout as a background session <version>, -ReportTo
dev-nginx.psm1 the server's nginx in front of a local stack: Debian's nginx, the house files, the repo's vhost unchanged imported by run-local.ps1

Every script prints its switches with -Help.

# from the shared-core checkout
./scripts/fleet-check.ps1                  # the apps whose repos changed
./scripts/fleet-check.ps1 -All             # every app, as many local stacks at once as memory holds
./scripts/fleet-check.ps1 -Own             # every own app, no cloned project
./scripts/fleet-version.ps1                # is everything pushed and running?
./scripts/fleet-deploy-script.ps1          # are the copies still identical?