0034 — Platform Status Dashboard

Status: Accepted

Date: 2026-06-23

ADO work item: AB#3074 (Platform Epic); Feature "Admin Platform Status Dashboard" created under Epic AB#3074

Deciders: Kristopher Turner (platform owner)

Cross-references: ADR 0005 (Observability), ADR 0006 (RBAC), ADR 0021 (Admin Portal)

---

Context

Platform administrators need operational visibility into the health of the running system — whether the API is serving, whether the database is reachable, what code version is deployed, and how long the service has been up — without leaving the Heritage Virginia web application.

Currently the /health endpoint returns only { status, timestamp }. Administrators must log into Azure Portal or query Azure Monitor / App Insights directly to understand service state. This creates friction during incident response and routine checks.

A lightweight status page served inside the admin portal (role = ADMIN) backed by a richer /health API response addresses this need without introducing external status-page SaaS dependencies.

Decision

We will expose a /app/admin/status page inside the admin portal that displays live platform health data sourced from an enriched /health API endpoint. The endpoint will be unauthenticated so that uptime monitoring and smoke checks can reach it without a token; the admin portal page is protected by the existing ADMIN role guard. The page links out to App Insights (appi-heritageva-prod in rg-heritageva-prod-eus, EUS) for deeper telemetry.

We will add a richer /health endpoint (DB check, commit SHA, uptime, service map) and surface the data in a dedicated admin-only status page at /app/admin/status, linking to App Insights for drill-down.

Alternatives considered

Option	Pros	Cons	Why not chosen
Richer /health + admin status page (chosen)	No new SaaS cost, co-located with admin portal, fast to build	Shows only what the API knows; no global CDN/DNS view	Chosen — fits free tier + admin portal pattern
Azure Monitor workbook embedded in app	Rich charts, native Azure	Requires iframe or MSAL auth; overkill for basic status	Not chosen — adds auth complexity + cost
Third-party status page (Statuspage, BetterStack)	Public visibility, subscriber notifications	Monthly cost, external service, not faith-/privacy-aligned	Not chosen — cost + external dependency
Polling from frontend only (no /health changes)	Zero backend change	Cannot report DB latency or commit SHA	Not chosen — insufficient data

Consequences

Positive

• Administrators see API reachability, DB connectivity, deployed commit SHA, and service uptime without leaving the app.
• The enriched /health response is also consumed by the CI smoke check (deploy.yml), providing a single source of truth.
• COMMIT_SHA build arg in the Dockerfile + workflow links every running container image to the exact Git commit, aiding incident triage.
• No external SaaS dependency; zero additional cost.
• Deep telemetry remains in App Insights (appi-heritageva-prod) — the status page links there rather than duplicating charting.

Negative / trade-offs

• The /health endpoint is unauthenticated; it intentionally exposes version and commit SHA publicly. This is standard practice for health probes and is not considered sensitive.
• DB latency shown on the status page is a point-in-time read, not a moving average — it gives a rough signal only.
• The page auto-loads once on mount; there is no real-time polling. An admin must refresh to see updated data.

Risks

• If the Prisma $queryRaw call hangs, the /health route itself may hang. Mitigate by adding a short query timeout or wrapping in Promise.race with a timeout in a follow-on task.
• Exposing the commit SHA allows an attacker to correlate the running version with known CVEs in that commit. Accepted — standard for community-operated open-source-adjacent platforms.

Amendment 2026-06-23 (AB#4388)

Per-surface build numbers will be surfaced alongside the platform version:

• Web: injected at build time via Vite's define config as __APP_VERSION__, sourced from package.json. The Vite build step reads process.env.npm_package_version and writes the value into the compiled bundle.
• API: already surfaced as version (npm_package_version) and commit (COMMIT_SHA) in the /health response. No change required.
• Mobile: surfaced via expo-constants expoConfig.version, which reads from app.config.js / app.json at runtime.

These values are shown in two places:

• About & Help page (all authenticated users): displays the version for the surface the user is currently on. No sensitive infra detail is shown here.
• Admin Status Dashboard (/app/admin/status, admin only): displays versions for all three surfaces (as known at build time), the API commit SHA, and DB connectivity — the existing data model plus the additions above.

Tracked: AB#4388.

---

References

• ADR 0005 — observability model (App Insights wired as primary telemetry)
• ADR 0006 — two-plane RBAC (admin role gates the status page)
• ADR 0021 — admin and ministry portal structure
• docs/internal/design/platform-status-dashboard.md — full data model, API contract, UI layout
• Azure resource: appi-heritageva-prod, rg-heritageva-prod-eus (East US)