Tenant Service — Migration Plan

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: SERVICE_OVERVIEW §9 Source reconciliation

1. Migration scope

Legacy module	New location	Notes
tenant (lifecycle + subscription + config)	tenant-service core	Schema updated to ULID IDs, RLS, status enum
hierarchy (HierarchyNode tree)	tenant-service	Merged — hierarchy is a tenant aggregate
access-policy (RBAC, roles, evaluate)	tenant-service	Moved from identity-service scope

2. Legacy FR mapping

Legacy prefix	New prefix
FR-TEN-*	FR-TENANT-*
FR-ACPOL-*	FR-TENANT-ACC-*

3. Database migration phases

Phase 1 — Tenant + Config (M0)

1. Create tenant schema; run Drizzle migrations.
2. Export legacy tenants and tenant_configurations rows; transform to ULID IDs.
3. Validate slug uniqueness; fix any collisions.
4. Deploy tenant-service; route admin tenant APIs from monolith.

Phase 2 — Hierarchy (M1)

1. Export legacy hierarchy_nodes rows; transform IDs; rebuild parent chain.
2. Validate hierarchy integrity (single root per tenant; no orphan nodes).
3. Update root_node_id in tenants table.
4. Verify identity-service license resolver uses new GET /internal/tenant/nodes/:id/ancestors.

Phase 3 — RBAC / access-policy (M1)

1. Export role definitions and role assignments from legacy access-policy module.
2. Map legacy role codes to built-in role set; create custom roles for tenant-specific roles.
3. Migrate role assignments with (userId, roleId, nodeId) triples.
4. Retire legacy access-policy service or module; route evaluate() to tenant-service.

Phase 4 — Membership reconciliation (M1)

1. Build org_memberships from legacy user-node assignment tables.
2. Link user_profiles to identity-service user_id values.
3. Validate: every role assignment has a corresponding org membership.

4. Tenant-by-tenant checklist

For each migrating tenant:

• Tenant row created with correct status and subscription dates.
• Root node ID backfilled.
• Hierarchy tree integrity verified (depth, parent chain).
• Roles migrated; built-in roles seeded.
• User profiles linked to identity-service user IDs.
• Role assignments validated.
• Config KV migrated and allow-list validated.
• Tenant admin notified of cutover.

5. Rollback plan

Phase	Rollback
Phase 1	Feature flag reverts admin calls to monolith
Phase 2	Hierarchy node queries re-routed to legacy
Phase 3	evaluate() reverted to legacy access-policy; dual-run for verification
Phase 4	Membership data preserved; re-import from backup

6. Open questions

• SCIM 2.0 provider sync — which service owns the SCIM endpoint? (identity-service bridge vs tenant-service)
• Handling tenants with custom roles that conflict with built-in role codes.