Runtime environment & white-label boot

Platform & Access · Runtime environment & white-label boot

Before anything renders, the app fetches a per-deployment config.json that sets the API host, environment and deploy names, the visual theme, the browser-tab title, Pusher credentials and the Fidcard / gift-card URLs — so one build serves several white-labelled clients.

Area	Platform & Access
Routes	application
Centre modules	always available
Staff levels	all (runs before login)
Models	—
UI label	(config.json)
Coverage	3 use cases · 1 happy · 3 failure

Known issues (1)

• 🟠 Medium — Runtime config failure is a blank page

How it works

routes/application.js#beforeModel awaits $.getJSON('config.json') and writes api.host (trailing slash stripped), api.namespace = 'v3', auth.env, auth.deployEnv, auth.fidecardUrl, auth.giftCardClientUrl, auth.giftCardAdminUrl, headData.theme (falling back to the module prefix), headData.title (the env name, also sent to Froged as the company) and the Pusher app key. Only one alternative theme ships in the repo (styles/themes/cbre.scss). A code comment says the env flag exists ‘to show bonus request only in cbre environment’, but no bonus-request code remains — the bonusRequest translation namespace is orphaned. After config, _setLanguage() and _loadCurrentUser() run, and every route change is tracked through both metrics.trackPage and analytics.page().

Use cases

Why someone opens this (3)

• Deploying the same frontend build for a second client with its own branding and API.
• Pointing a staging deployment at a staging API without rebuilding.
• Giving each environment a distinguishable browser-tab title.

Path map

flowchart LR
    F(["Runtime environment and white-label boot"]):::feat
    F --> H1["Boot with a valid config"]:::ok
    F -.-> X1["config.json missing or malformed"]:::bad
    F -.-> X2["Pusher block absent"]:::bad
    F -.-> X3["Theme not shipped"]:::bad
    classDef feat fill:#4a5c8a,stroke:#4a5c8a,color:#ffffff,font-weight:bold
    classDef ok fill:#e3f1ea,stroke:#0d6b42,color:#0d4a2e
    classDef bad fill:#f7e6e2,stroke:#9a2d1c,color:#6e1f13

Happy paths

Boot with a valid config

1. Browser loads the app; config.json is fetched from the deployment root.
2. API host, theme, title and Pusher keys are applied and Pusher is initialised.
3. Translations load, then the current user is resolved or the user is sent to login.

Failure paths

config.json missing or malformed

Cause — Deployment without the file, or invalid JSON.

What happens — beforeModel rejects before any UI exists — the user sees a blank page with no message. The single hardest failure in the product.

Pusher block absent

Cause — data.pusher not set for the environment.

What happens — App key and env fall back to empty strings; realtime features (signatures, AI images) silently never update.

Theme not shipped

Cause — data.theme names a theme with no stylesheet.

What happens — No guard — the default styling is used without warning.

QA checklist

Tick these off while regression-testing this feature. The boxes are plain Markdown, so progress is visible in git diffs.

• ✅ Boot with a valid config
• ⛔ config.json missing or malformed
• ⛔ Pusher block absent
• ⛔ Theme not shipped

Implementation

• app/routes/application.js
• public/config.json (deployed per environment)
• app/styles/themes/cbre.scss
• app/services/head-data.js

Related

• Same area — Staff login · Password reset request · Password update from reset link · Change own password · Idle auto-logout · Centre switching & multi-centre scoping · Server-incident banner · Desktop (home dashboard) · Back-office interface language · In-app help & support chat (Froged)

---

Generated from doc/feature-inventory.json · id platform-runtime-config · commit 276788ca6