Why /api is relative

The platform contract — one artifact, every environment

What this file is. The behavior contract for the platform half of the environment story: one build artifact, a relative /api, per-box stores, and the vendoring rule. Its sibling is deploy/functional_requirements_environments.md, which owns the serving half — which server_name answers which name, from which docroot, behind which cert lineage.

Every requirement is a check that can pass or fail. The map is docs/architecture_platform.md.

1 · One artifact, every environment

• The frontend calls /api, relatively. No page carries an absolute API origin, a PUBLIC_API_URL, or any other build-time environment constant. Check: grep -rn 'PUBLIC_API\|https://onefrontier.ai/api' web/src returns nothing.
• nginx resolves the environment from the Host header. The same web/dist build serves the apex, the stage box, and every dev box; only the request's hostname differs. Check: the same web/dist served under two different server_names returns byte-identical HTML, and each HTML body's API calls are relative.
• A page's API address is its own origin. A page fetched from <box>.onefrontier.ai reaches <box>.onefrontier.ai/api, which proxies to that box's api container. Check: curl -sk --resolve <box>.onefrontier.ai:443:10.10.0.124 https://<box>.onefrontier.ai/api/health answers from that box.

2 · Per-box stores

• No shared database. The api's ONEF_DATABASE_URL points at 127.0.0.1; the ClickHouse DSN points at 127.0.0.1. Neither names a peer. Check: grep -rn '10\.10\.' docker/ deploy/up.sh | grep -i 'postgres\|clickhouse' returns no datastore address.
• A dev box can be destroyed without consequence. Dropping and recreating the postgres and clickhouse volumes on one box leaves every other box's data intact, and deploy/up.sh re-seeds the dropped one. Check: docker volume rm on one box, then deploy/up.sh, then curl /api/health is ok and the schema is present.

3 · The vendoring rule

• No third-party request from any page. Fonts, stylesheets, scripts, icons, images, and every runtime subresource live under web/public/. Check: grep -rhoE 'src="https?://[^"]+' web/dist returns nothing.
• The CSP is default-src 'self' on every page, so a hotlink fails at the first load instead of leaking quietly.
• script-src 'none' sitewide, except the console page, which allows 'self' and connect-src 'self' for its live /api/health pill. Check: every page's meta CSP is script-src 'none' except /console/.
• No inline style= attribute anywhere — the CSP is style-src 'self', so an inline style is silently dropped and the layout degrades with no error. Check: grep -rn 'style=' web/src returns nothing.
• Every vendored file is declared. web/public/vendor/MANIFEST.md names each file's upstream URL and version. Check: every file under web/public/vendor/ appears in the manifest.

4 · The build

• The site is a static build with no runtime dependency. npm run build produces web/dist; no node process runs on a serving host.
• The kit's documents are rendered from the repository at build, never copied. An edit to package/README.md changes the site on the next build. Check: web/src/data/docs.ts names a source path for every doc, and web/src/lib/kitdocs.ts reads it.
• Every internal link resolves. Check: python3 web/scripts/check-links.py reports broken internal references: 0.

Acceptance

A change to the build or the platform passes when:

1. One web/dist serves the apex and a dev box, and each page's API calls are relative.
2. deploy/up.sh on a clean box brings up postgres, clickhouse, and the api, and the site's title renders at https://<box>.onefrontier.ai/.
3. web/dist contains no absolute API origin, no inline style=, and no third-party src=.
4. The console page's status pill reads /api/health from its own origin.
5. Every kit doc page renders the repository's own markdown.