Platform Administration (single Administration feature)
Status: Normative (product + UX)
Version: 1.0
Date: 2026-04-04
Related: MODULE_SHARED_STANDARDS.md · PLATFORM_REALM_ROLES.md · PERSONA_CAPABILITY_MATRIX.md · modules/iam/SPEC.md · modules/access-policy/SPEC.md · modules/tenant/SPEC.md · modules/platform-admin/SPEC.md · modules/hierarchy/SPEC.md · modules/facility-management/SPEC.md · modules/provider-directory/SPEC.md · modules/licensing/SPEC.md · modules/audit/SPEC.md · modules/config-resolver/SPEC.md (Draft)
1. Purpose
This document defines the single Administration product feature in the staff EHR client (ehr-web): one route prefix, one layout, one information architecture. Sub-features (facilities, providers, identity, tenant/platform, licensing, audit, system health) are shown only when permitted by the user’s Keycloak realm role and enforced again on the server.
Backend behavior remains owned by existing bounded-context specs; this document ties personas → UI capabilities → services without duplicating per-service FR catalogs.
2. Product principles
| ID | Statement |
|---|---|
| FR-ADM-UMB-001 | The Administration feature SHALL use one client route tree under a single prefix (e.g. /admin) with one shell layout (navigation, breadcrumbs). |
| FR-ADM-UMB-002 | Realm roles SHALL determine which Administration submodules and actions are visible in the UI (capability matrix §4). |
| FR-ADM-UMB-003 | Authorization for data mutations and sensitive reads SHALL still use Access Policy POST /internal/access/evaluate (and related IAM contracts) per iam/SPEC.md BR-IAM-003/004 — realm roles are not sufficient for fine-grained decisions. |
| FR-ADM-UMB-004 | The UI SHALL not duplicate full page trees per persona; navigation and action affordances SHALL be driven by a capability matrix (role × submodule × access level). |
| FR-ADM-UMB-005 | Deep links to a submodule the user’s role cannot access SHALL return 403 from APIs and a safe access denied state in the client. |
3. Two layers of access control
- Transport persona (Keycloak realm roles) — Coarse gating: which Administration areas exist in the menu. Canonical role names: PLATFORM_REALM_ROLES.md.
- Resource authorization (Access Policy + IAM) — Fine-grained: which actions on which hierarchy nodes. See access-policy/SPEC.md; evaluation pattern PERSONA_CAPABILITY_MATRIX.md (PHI / ABAC follow-up).
4. Capability matrix (normative)
Access level: none · read · write (write implies read).
Submodules: dashboard · facilities · providers · identity · platform · licensing · audit · systemHealth
| Realm role | dashboard | facilities | providers | identity | platform | licensing | audit | systemHealth |
|---|---|---|---|---|---|---|---|---|
super-admin | write | write | write | write | write | write | read | read |
tenant-admin | write | write | write | write | read | read | read | none |
admin-staff | read | read | read | read | none | none | read | none |
auditor | read | read | read | read | read | read | read | read |
physician, nurse, front-desk, lab-staff, pharmacy-staff, technician, patient | none | none | none | none | none | none | none | none |
Notes:
- Tenant-admin
platform: Tenant-scoped configuration only (e.g. tenant FR-TEN-007..008); not cross-tenant tenant lifecycle. Super-admin performs tenant create/activate/suspend (tenant FR-TEN-001..005). - Tenant-admin
licensing: licensing SPEC MVP0 — Tenant Admin views effective licenses; assignment is Super Admin unless product revises. - Admin-staff: Onboarding/reporting alignment with iam §2 Admin Staff — no PHI by default; matrix keeps platform/licensing at
noneunless product extends. - Auditor: Read-only everywhere applicable; audit search/export per audit FR-AUD-QRY-*. UI MUST disable mutating controls even if APIs were misconfigured.
5. Information architecture (single IA, filtered nav)
Same top-level areas for all roles that enter Administration; items hidden or disabled per §4.
| Area | User workflows | Owning specs |
|---|---|---|
| Dashboard | Role-specific summary widgets (health, tenant summary, audit shortcuts) | This doc + platform-admin health aggregate |
| Facilities | Hierarchy tree CRUD (hierarchy); operational overlay — beds, rooms, resource catalog (facility-management) | hierarchy + facility-management |
| Providers | Directory profile, credentials, endpoints (provider-directory); identity lifecycle (iam); node memberships (hierarchy) | iam + provider-directory + hierarchy |
| Identity & access | Access Policy roles/permissions and assignments at nodes (access-policy); Keycloak realm role changes remain operator/IAM procedures documented in runbooks | access-policy + iam |
| Platform & tenant | Super Admin: tenant lifecycle, global platform KV, feature flags (tenant, platform-admin). Tenant Admin: tenant profile + TenantConfiguration | tenant + platform-admin |
| Licensing | Module catalogue, assignments to nodes (licensing) | licensing |
| Audit | Query/export (audit) | audit |
| System health | Aggregate health (platform-admin FR-ADM-HLT-*) | platform-admin |
6. Data ownership boundaries (reminder)
| Concept | Owner |
|---|---|
| Organisation graph (nodes, edges, profiles) | Hierarchy Service |
Facility operational data (beds, FacilityNodeConfig, resources) | Facility Management module / facility |
User identity, ProviderProfile, service accounts | IAM Service + Keycloak |
| Provider directory / credentials / interop endpoints | Provider Directory Service |
RBAC roles, permissions, evaluate() | Access Policy Service |
| Tenant record, subscription fields, tenant KV config | Tenant Service |
| Global platform KV, feature flags, health aggregate | Platform Admin Service |
| Module licences on nodes | Licensing Service |
| Immutable audit store & query API | Audit Service |
7. Configuration model
| Layer | Mechanism | Spec reference |
|---|---|---|
| Platform-wide | Platform Admin PlatformConfig keys + FeatureFlag | platform-admin §3 |
| Tenant | TenantConfiguration KV (e.g. branding.primary_color, branding.logo_url) | tenant §3.2 |
| Feature vs licence | Independent — BR-ADM-002 | Both MUST be visible in admin UI where relevant |
| Future UI/theme DAG | Config Resolver (Draft) | config-resolver §1 — see §10 |
8. Service orchestration (illustrative)
- Tenant activation — Orchestrated by Tenant Service (tenant §7): Hierarchy root → IAM Tenant Admin → Licensing seeds → events.
- Provider onboarding (full) — Typically: IAM user + ProviderProfile → Provider Directory → Hierarchy memberships → Access Policy role assignments; order and idempotency SHALL match TECHNICAL_REQUIREMENTS of each service.
Admin UI SHOULD surface these as guided flows without re-implementing business rules in the client (BFF/route handlers forward to domain APIs).
9. Traceability (umbrella → existing FRs)
| Umbrella | Maps to (examples) |
|---|---|
| Facilities | FR-HIER-NODE-, FR-HIER-EDGE-, FR-FAC-001..010 |
| Providers | FR-IAM-USR-, FR-IAM-PROV-, FR-PROV-001..008 |
| Identity & access | Access Policy FRs; IAM authentication FRs |
| Platform & tenant | FR-TEN-, FR-ADM-CFG-, FR-ADM-FF-* |
| Licensing | FR-LICN-* |
| Audit | FR-AUD-* |
| System health | FR-ADM-HLT-* |
10. Config Resolver alignment (future)
config-resolver/SPEC.md is Draft. When normative, Administration SHALL add theme preset / design token management UI resolved through Config Resolver; until then, branding remains tenant KV and platform feature flags per §7. No client SHALL depend on Config Resolver for MVP Administration shipping.
Implementation pointer: In-product deferral note: apps/ehr-web/src/views/admin/ConfigResolverNote.tsx (embedded on the Platform & tenant admin view).
11. Non-functional
- i18n / RTL: MODULE_SHARED_STANDARDS.md §4.
- Audit: Administrative mutations MUST emit audit trails per owning services; Administration SHALL not bypass audit.
- Performance: Nav and capability resolution SHOULD be derivable from session claims without N+1 calls where possible; optional
GET /iam/providers/:id/access-contextfor UI hints per iam.
12. Client implementation map
| Path | Purpose |
|---|---|
apps/ehr-web/src/lib/admin/admin-capability-matrix.ts | Normative matrix + helpers |
apps/ehr-web/src/app/(dashboard)/admin/layout.tsx | Administration shell + guard |
apps/ehr-web/src/views/admin/* | Admin pages and shared UI |