Super Admin Portal — Platform-Wide Management

The platform operator's seat — manages every organisation, every FHIR partition, every audit log, every Mastra agent and the cross-tenant diagnosis-engine — explicitly outside any single clinic's scope (X-Clinic-ID: platform, fetchOrg: false).

Business Purpose

Every multi-tenant system needs one role that sees across tenants — to provision new clinics, audit cross-tenant security events, monitor FHIR partition health, manage shared LLM/Mastra studios, and respond to GDPR/data-export requests. In HMS that role is SUPER_ADMIN and its surface is /portal/super-admin. It is not a "more powerful clinic admin"; the gateway explicitly overrides X-Clinic-ID to the literal 'platform' for super-admins (see proxy-gateway §route.ts:134-139), so every backend call this portal makes is cross-tenant by design.

For the investor narrative, this is the seat that runs the SaaS — one person can onboard a clinic, watch FHIR ingestion, manage AI/Mastra configuration, and resolve a tenant-isolation defect without leaving the product. For the developer, it's a worked example of "cross-tenant by default" — the inverse of every other portal.

Audiences

• Investor: the SaaS operator's cockpit. Confirms that the platform ships with an explicit cross-tenant role rather than relying on side-channel DB access — every admin action is gated and audit-logged.
• Clinical buyer: not for them. Customers cannot self-serve a super-admin account; the role is provisioned by Dudoxx ops only.
• Developer/partner: the canonical example of fetchOrg: false and X-Clinic-ID: 'platform'. Three places in code embed the super-admin override — config, BFF route handler, server backendFetch — all three must stay in sync.
• Internal (ops/support): this is YOUR daily portal. Documents what surfaces exist (organizations, users, fhir, audit-logs, monitoring, mastra-studio, data-integrity, integrations, localization) and the read-mostly contract.

Architecture

Config — the only one with fetchOrg: false

ddx-web/src/lib/portal/role-configs.ts:148-161:

export const SUPER_ADMIN_CONFIG: RolePortalConfig = {
  roleKey: 'super-admin',
  authRequirement: 'SUPER_ADMIN_ONLY',
  roleBadge: { role: 'SUPER_ADMIN', labelKey: 'roles.super_admin',
               icon: ShieldStarIcon, variant: 'danger' },
  brandNameKey: 'title',
  brandNameNamespace: 'superAdmin',
  organizationNameKey: 'platformName',
  fetchOrg: false,
};

fetchOrg: false instructs createRoleLayout to skip the per-render organization fetch — a super-admin has no single org. brandNameNamespace: 'superAdmin' and organizationNameKey: 'platformName' make the chrome read e.g. "Platform Administration · Dudoxx Platform" instead of a clinic name.

Cross-tenant by gateway design

The three places X-Clinic-ID: 'platform' is set:

1. ddx-web/src/app/api/v1/[[...path]]/route.ts:134-139 — catch-all Route Handler: isSuperAdmin || !clinicId → 'platform'.
2. ddx-web/src/lib/api/backend-client.ts:229-232 — backendFetch (Server Components): same condition, same override.
3. ddx-web/src/lib/api/backend-client.ts:685-687 — backendFetchRaw (binary downloads): same override for SUPER_ADMIN streams.

All three must agree. The ddx-api backend's tenant interceptor treats X-Clinic-ID: platform as the explicit cross-tenant marker (see tenant-isolation).

Layout — same one-line factory

ddx-web/src/app/[locale]/portal/super-admin/layout.tsx:15-20:

function SuperAdminNav() { return <PortalNavigation roleKey="super-admin" />; }
export default createRoleLayout(SUPER_ADMIN_CONFIG, SuperAdminNav);

The factory honours fetchOrg: false and skips the org fetch — the rest of the shell composition is identical to every other portal.

Routes

portal/super-admin/
├── layout.tsx                  → factory with SUPER_ADMIN_CONFIG
├── page.tsx                    → redirects to dashboard
├── dashboard/                  → cross-org KPIs + recent orgs
│   ├── page.tsx                  • getQuickStatsServer + getAllOrganizationsServer
│   ├── actions.ts                • server actions for stats refresh
│   └── DashboardStatsClient.tsx
├── organizations/              → cross-tenant org management
│   ├── page.tsx                  • role distribution + orgs table
│   ├── OrganizationsClient.tsx
│   ├── create/                   • new-org wizard
│   └── [slug]/                   • per-org drill-in
├── users/                       → all platform users
├── fhir/                        → HAPI FHIR partition overview
│   ├── page.tsx                  • by-type + by-partition stats
│   └── [clinicId]/               • per-partition browser
├── audit-logs/                  → cross-tenant audit trail
├── data-integrity/              → orphan/refcount checks
├── monitoring/                  → service health, queues
├── diagnosis-engine/            → cross-org diagnosis quality reports
├── integrations/                → Tomedo + third-party connectors
├── localization/                → i18n key audit + translation health
├── mastra-studio/               → embedded Mastra Studio
├── cms/, help/, messages/, messenger/, profile/, settings/
├── analytics/                   → cross-org analytics
├── loading.tsx, error.tsx, not-found.tsx

super-admin/server.ts — cross-org data layer

ddx-web/src/lib/api/clients/super-admin/server.ts exports server-only functions (getQuickStatsServer, getAllOrganizationsServer, getEnhancedFhirStatsServer, etc.). Each calls backendGet(...) — because the user is SUPER_ADMIN, X-Clinic-ID: 'platform' is set, and ddx-api returns cross-tenant aggregates.

Example — dashboard

ddx-web/src/app/[locale]/portal/super-admin/dashboard/page.tsx:21-44:

const [statsResponse, orgsResponse] = await Promise.all([
  getQuickStatsServer(),
  getAllOrganizationsServer({ limit: 6 }),
]);

Two parallel cross-tenant fetches, both via the gateway, both pinned to 'platform'.

Example — FHIR oversight

ddx-web/src/app/[locale]/portal/super-admin/fhir/page.tsx:25-58:

const fhirResponse = await getEnhancedFhirStatsServer();
// ... resourcesByType, byPartition
const serverStatus = {
  connected: fhirData?.serverStatus === 'up',
  endpoint: 'Via NestJS Gateway',   // SECURITY: never leak FHIR URL to client
  ...
};

Note :50-58: the FHIR server URL is never exposed to the client. The super-admin sees "Via NestJS Gateway", not http://hapi:8080/fhir — even super-admins go through the BFF.

Tech Stack & Choices

Rejected: making SUPER_ADMIN part of ADMIN_PLUS only (it is in ADMIN_PLUS for admin surfaces, but reaching the super-admin portal requires the strict SUPER_ADMIN_ONLY check); rendering FHIR data via a direct HAPI URL (would leak the partitioning model to the browser); shipping a single "Admin" portal with role-based show/hide (the cross- tenant override is a different gateway path, not a UI gate).

Data Flow

1. Walid logs in as SUPER_ADMIN → JWT role: SUPER_ADMIN, organizationId: <his test org>.
2. Browser hits home.dudoxx.com/en/portal/super-admin (or any non-trigram apex/management host).
3. proxy.ts:51-57 — apex/non-3-letter host → no trigram, no X-Clinic-ID injection.
4. super-admin/layout.tsx runs the factory: requireRoleAccess('SUPER_ADMIN_ONLY', locale) returns the user; fetchOrg: false skips the org fetch; chrome renders.
5. dashboard/page.tsx calls Promise.all([getQuickStatsServer(), getAllOrganizationsServer({ limit: 6 })]).
6. Each call goes through backendGet → backendFetch → because session.user.role === 'SUPER_ADMIN', clinicId = 'platform' → X-Clinic-ID: platform header → ddx-api returns cross-tenant aggregates.
7. Audit logger (server side) writes a SUPER_ADMIN_DASHBOARD_VIEW entry — every super-admin action is audit-trailed (see audit-logging).

Implicated Code

• ddx-web/src/lib/portal/role-configs.ts:148-161 — SUPER_ADMIN_CONFIG with fetchOrg: false.
• ddx-web/src/lib/portal/role-configs.ts:198 — registry entry.
• ddx-web/src/app/[locale]/portal/super-admin/layout.tsx:15-20 — factory invocation.
• ddx-web/src/app/[locale]/portal/super-admin/page.tsx:7-12 — root redirect.
• ddx-web/src/app/[locale]/portal/super-admin/dashboard/page.tsx:21-44 — dual Promise.all cross-tenant fetch.
• ddx-web/src/app/[locale]/portal/super-admin/organizations/page.tsx:69-165 — orgs table with role distribution.
• ddx-web/src/app/[locale]/portal/super-admin/fhir/page.tsx:25-58 — FHIR partition overview; note :50-58 never exposes the FHIR URL.
• ddx-web/src/lib/api/clients/super-admin/server.ts — server-only cross-org clients (getQuickStatsServer, getAllOrganizationsServer, getEnhancedFhirStatsServer).
• ddx-web/src/app/api/v1/[[...path]]/route.ts:134-139 — gateway override (BFF path).
• ddx-web/src/lib/api/backend-client.ts:229-232 — server-component override.
• ddx-web/src/lib/api/backend-client.ts:685-687 — raw/binary stream override.

Operational Notes

• Three places enforce 'platform' — route.ts:134-139, backend-client.ts:229-232, backend-client.ts:685-687. If a code review proposes a fourth fetch path, the override MUST be replicated or the super-admin silently scopes to their JWT org and the dashboard appears empty.
• fetchOrg: false is load-bearing — without it, the factory would call /organizations/<superAdmin.organizationId> per render; the super-admin doesn't have one stable org, so the chrome would flicker or 404. Don't "fix" by giving super-admins an org.
• FHIR URL never client-side — super-admin/fhir/page.tsx:55 hard-codes endpoint: 'Via NestJS Gateway'. If a UI proposal asks for "the real URL", reject — defense-in-depth even for super-admins.
• Audit every action — every super-admin write (create org, update user, mutate FHIR) is audit-logged with userId + targetOrganizationId. See audit-logging.
• requireRoleAccess('SUPER_ADMIN_ONLY') is the strictest gate — not a member of ADMIN_PLUS, not satisfied by STAFF_PLUS. Spoofing protection: the JWT role is set at login from the DB, not from a client cookie.
• Localization editor in-portal — super-admin/localization/ surfaces the i18n key auditor (cf. the i18n-key-auditor skill). It edits src/locales/{en,fr,de}/*.json indirectly via API; do not write JSON from the browser.
• mastra-studio/ — embeds the Mastra Studio iframe; the super-admin is the operator of the Mastra/TUCAN backplane.
• data-integrity/ — runs orphan checks, refcount audits across Prisma + FHIR + MinIO; results stream via SSE.

Related Topics

• Multi-Portal Architecture — the shared factory and registry.
• Admin Portal — the per-clinic counterpart; SUPER_ADMIN is implicitly a member of ADMIN_PLUS but reaches the super-admin shell only via the strict gate.
• Web Proxy Gateway — the BFF that overrides X-Clinic-ID to 'platform' for SUPER_ADMIN.
• Tenant Isolation — what ddx-api does when it receives X-Clinic-ID: platform.
• FHIR Partitions / Tenancy — the partition model the super-admin oversees.
• Audit Logging — super- admin actions are audit-logged.
• RBAC Roles — where SUPER_ADMIN_ONLY sits in the auth tier list.