Tenant Service — Epics
Service: tenant-service Epic prefix: TENANT-EPIC Last updated: 2026-04-18
Epics
TENANT-EPIC-01 — Tenant lifecycle and subscription management
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Onboard, activate, suspend, terminate tenants and manage subscriptions |
| Status | In Progress |
| Priority | Must |
| Labels | service:tenant, domain:tenant, slice:S0 |
| Components | lifecycle-module, subscription-module |
| Fix version | M0 |
| FR references | FR-TENANT-001..006, FR-TENANT-011..013 |
| Legacy FR refs | FR-TEN-001..006, FR-TEN-011..013 |
| Dependencies | TENANT-EPIC-03 (activation orchestration), cross-service: IDENT-EPIC-01 |
| Rollup status | Partial |
Business outcome: Platform operators can onboard healthcare organizations as tenants, controlling the full lifecycle from pending registration through commercial activation to suspension or termination. Subscription changes are tracked and emit events consumed by licensing.
Description:
Delivers CRUD for tenant records, the activation saga (hierarchy node + admin user + always-on license seeding), suspension with session invalidation, reactivation, and termination. Subscription tier, dates, and expiry events are managed here. All state transitions are auditable and emit domain events. Freeze: slug is immutable once created. terminated is terminal.
Stories: TENANT-US-001, TENANT-US-002
TENANT-EPIC-02 — Tenant configuration and governance
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Tenant admin manages profile, config KV, and hierarchy profiles |
| Status | In Progress |
| Priority | Must |
| Labels | service:tenant, domain:tenant, slice:S0 |
| Components | config-module |
| Fix version | M0 |
| FR references | FR-TENANT-007..010 |
| Legacy FR refs | FR-TEN-007..010 |
| Dependencies | TENANT-EPIC-01 |
| Rollup status | Partial |
Business outcome: Tenant administrators can update their organization's display settings, locale, MFA requirements, and session timeouts through a governed KV store. Unknown config keys are rejected, preventing misconfiguration.
Description: Provides PATCH on tenant profile (displayName, contactEmail, locale, timezone) and PUT/DELETE on per-tenant config KV pairs. Config keys are validated against a platform allow-list (BR-TEN-005). Country code determines default hierarchy profile. Super Admin can override hierarchy profile ID.
Stories: TENANT-US-003, TENANT-US-004
TENANT-EPIC-03 — Activation orchestration reliability
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Resilient multi-step activation saga with idempotency and bounded retry |
| Status | To Do |
| Priority | Must |
| Labels | service:tenant, domain:tenant, slice:S0 |
| Components | lifecycle-module, activation-saga |
| Fix version | M0 |
| FR references | FR-TENANT-014, FR-TENANT-ENH-001 |
| Legacy FR refs | FR-TEN-014, FR-TEN-ENH-001 |
| Dependencies | TENANT-EPIC-01, cross-service: IDENT-EPIC-01, FAC-EPIC-01 |
| Rollup status | Not started |
Business outcome: Tenant activation never leaves the platform in a partial state. Transient downstream failures are recovered via bounded retry. Idempotency tokens prevent duplicate activations.
Description: Wraps the activation saga (hierarchy node creation → admin user seeding → license seeding) in a bounded exponential backoff pattern (3 attempts, 1s/2s/4s). Tenant remains PENDING on exhaustion; alert fires. Idempotency-Key header prevents double-activation on retry. Partial effects are idempotent (create-or-return semantics in downstream clients).
Stories: TENANT-US-005, TENANT-US-006
TENANT-EPIC-04 — Org hierarchy management
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Create and manage multi-level org hierarchy (facility → department → ward) |
| Status | To Do |
| Priority | Must |
| Labels | service:tenant, domain:tenant, slice:S1 |
| Components | hierarchy-module |
| Fix version | M1 |
| FR references | FR-TENANT-HIER-001..006 |
| Legacy FR refs | — |
| Dependencies | TENANT-EPIC-01 |
| Rollup status | Not started |
Business outcome: Tenant admins can reflect their org structure in the system — from the root organization down to individual wards and beds. This hierarchy drives membership, authorization scope, and licensing inheritance.
Description:
Delivers CRUD for HierarchyNode (create, update, archive). Node type constraints enforced by HierarchyProfile (AFG_MOPH, UAE_DOH, PRIVATE_HOSPITAL). Parent cross-tenant validation enforced. Ancestor chain query supports identity licensing resolver. Archive is soft-delete; archived nodes' children cannot have new members.
Stories: TENANT-US-007, TENANT-US-008
TENANT-EPIC-05 — User profiles and org membership
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Manage user profiles and multi-node org memberships |
| Status | To Do |
| Priority | Must |
| Labels | service:tenant, domain:tenant, slice:S1 |
| Components | membership-module, profile-module |
| Fix version | M1 |
| FR references | FR-TENANT-USR-001..006 |
| Legacy FR refs | FR-IAM-USR-001..003 (partial) |
| Dependencies | TENANT-EPIC-04, cross-service: IDENT-EPIC-01 |
| Rollup status | Not started |
Business outcome: Clinical users and staff are associated with the correct facilities and departments. Their professional profiles (specialty, credentials) are maintained alongside their org placement, enabling accurate authorization context.
Description:
User profiles are JIT-created when identity.user.registered.v1 is received. Membership assignment links a user to a node with a status lifecycle. Invitation flow creates a profile + emits tenant.user.invited.v1 for communication-service. Profile updates cover name, specialty, credentials.
Stories: TENANT-US-009, TENANT-US-010
TENANT-EPIC-06 — RBAC and authorization evaluate
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Role lifecycle, role assignments, and RBAC/ABAC evaluate() decision endpoint |
| Status | To Do |
| Priority | Must |
| Labels | service:tenant, domain:authorization, slice:S0/S2 |
| Components | rbac-module, abac-module |
| Fix version | M0 (RBAC), M2 (ABAC) |
| FR references | FR-TENANT-ACC-001..010 |
| Legacy FR refs | FR-ACPOL-001..010 |
| Dependencies | TENANT-EPIC-05, cross-service: IDENT-EPIC-01 |
| Rollup status | Not started |
Business outcome: All authorization decisions across the platform flow through a single evaluate() endpoint. Built-in roles cover clinical workflows; tenant admins can create custom roles. ABAC policies add attribute-level control in S2.
Description:
Delivers built-in role seeding (TENANT_ADMIN, CLINICIAN, NURSE, PATIENT), custom role CRUD, role assignment at (user, node) pairs, and the POST /api/v1/tenants/:id/access/evaluate endpoint returning { decision, reasons }. ABAC attribute policies (M2) add condition-based evaluation using node attributes and user profile data.
Stories: TENANT-US-011, TENANT-US-012, TENANT-US-013
TENANT-EPIC-07 — Security, isolation, and quality gates
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Tenant isolation, GDPR, quality coverage, and observability gates |
| Status | To Do |
| Priority | Must |
| Labels | service:tenant, domain:platform, slice:S0..S4 |
| Components | cross-cutting |
| Fix version | M0..M3 (rolling) |
| FR references | FR-TENANT-NFR-001..006 |
| Legacy FR refs | BR-TEN-005, BR-TEN-006, NFR-TEN-001..003 |
| Dependencies | All TENANT-EPICs |
| Rollup status | Not started |
Business outcome: tenant-service meets platform reliability, isolation, and compliance targets. RLS isolation is continuously verified. Event publish health is monitored with alerting.
Description: Covers: mandatory tenant-isolation integration test, outbox/inbox tests, coverage ≥ 80%, activation p95 ≤ 500 ms SLO, event publish failure alerting, GDPR erasure propagation, and HIPAA audit trail. Rate limiting and freeze mode are scoped to S4/M3.
Stories: TENANT-US-014, TENANT-US-015