Hilo B2B Dashboard — System Architecture

Pragmatic single-monolith architecture for the B2B dashboard. Next.js for app + API. Postgres for data. Azure Blob WORM for tamper-evident audit logs. Compliance baked into the request path, not bolted on. No microservices, no MySQL, no Python — every piece exists for a reason.

Interaction: drag to pan · scroll to zoom · double-click to reset · fullscreen button per diagram.

0. Components — what each thing is, why we have it

Every component in the build, before any diagrams. Struck-through cards = explicitly excluded with reasoning.

1. System Architecture Overview — everything at once

The full map. Browser top-left, identity provider top-center, Azure region holds the whole stack. Two write paths to data: Next.js writes to Postgres, audit middleware additionally writes immutable copies to Blob WORM. No path bypasses the middleware stack.

Reading the diagram: The doctor's browser is the only public ingress. App Service terminates TLS. Next.js middleware runs in this order on every request: authenticate → authorize → scope → audit. Postgres holds business data and a fast-query audit log. Azure Blob WORM holds the immutable, regulator-verifiable copy of every audit event. Identity is fully delegated to Entra External ID — Hilo never stores a password.

2. A Request's Journey — what happens when a doctor clicks "view patient"

An HCP clicks on a patient in the dashboard. Walk through every middleware layer the request passes through, what each one verifies, and what gets written where.

Why the middleware order matters: authenticate first (no identity = stop). Then authorize (does this role have read:patients permission). Then scope (filter by org_id and assignment list — even an authorized user can only see their own slice). Then audit (we log before returning data, so a server crash mid-response still leaves a trace). The query never runs without all four passing.

3. RBAC + Tenant Scoping — how a clinic only sees its own patients

Every B2B customer is a tenant. Inside each tenant, users have roles. The architecture enforces both: tenant isolation (an HCP at Clinic A cannot see Clinic B's patients) and role-based scope (an HCP user only sees their assigned patients; an HCP admin sees all org patients).

Why enforce at the database layer too: the Next.js middleware filters every query by org_id and assignment list. But we add Postgres Row-Level Security as a second layer. If a future bug in the app forgets to scope a query, RLS rejects it at the DB. Defense in depth — same patient data, two independent enforcement layers, both have to fail for cross-tenant leakage to occur.

4. Tamper-Evident Audit Logging — why regulators can trust this

Every audited action is dual-written. The Postgres copy is for fast app-side queries (e.g. "show me everything user X did this week"). The Azure Blob WORM copy is the legal record — immutable, retention-locked, separately accessible to auditors.

The trust model in plain English: Hilo can read the WORM blob. Hilo cannot modify or delete it. Azure's Storage Immutability service enforces this at the platform layer — not the app, not Hilo's IAM policy. Regulators get a read-only SAS token that lets them list and download blobs directly from Azure, bypassing Hilo entirely. If the Postgres audit log and the WORM archive ever disagree, the WORM archive is the authoritative answer — and only Hilo's app can have tampered with the Postgres copy.

5. GDPR + HIPAA Compliance Flows — consent, residency, right to erasure

Three compliance flows are wired into the system architecture, not added later: explicit consent (Article 9 special category data), data residency (EU patients stay in EU regions), and right to erasure (Article 17). Each one is enforced in middleware, so no API path can skip it.

Reading the flow: a patient grants consent → consent middleware records it (Postgres + WORM). When an HCP later queries that patient's data, the scope middleware first checks the live consent record. If consent is revoked, the query returns nothing — even though the row still exists in Postgres. Right to erasure is a soft delete with a scheduled hard-delete job; audit logs are preserved (regulators need them) but every consumer query now treats the patient as gone.

6. Device Data Flows — HCP-managed vs patient-managed

The two device-ownership models look like the same dashboard view but are completely different data flows. The HCP-managed flow is buildable for the May 28th milestone. The patient-managed flow needs a B2C → B2B data bridge that depends on the mobile app team.

Time of measurement vs time of sync: HCP-managed bands buffer days of data and only sync when the patient returns to the clinic. The dashboard shows both timestamps — "last reading 5 days ago, last synced 1 hour ago" — so a doctor never reads stale-but-unsynced data as a clinical event.

7. Deployment + Operations — from git push to production

One Next.js container. One Postgres database. One Blob Storage account. CI/CD via GitHub Actions. Staging slot for safe pre-prod verification. Zero-downtime deploys via App Service slot swap.

Why slot swap: the new build deploys into the staging slot, runs smoke tests against a copy of prod traffic, and only swaps in if healthy. If the new version is broken, swap back instantly — no downtime, no panic. Database migrations are always backward-compatible (add columns, never drop) so rollbacks don't break the schema.

8. Open Architecture Decisions

Decisions that need Hilo input before code is written. Not for the dev team to make alone.