Config Service — Migration Plan
Status: populated
Owner: TBD
Last updated: 2026-04-18
Companion: Service Template
1. Migration Context
The config-service replaces a fragmented pattern where each UI boundary made 5–7 individual API calls to determine permissions, visible UI elements, and theming. The legacy pattern existed in:
- Ad-hoc feature flag checks in frontend components (hardcoded guards)
- Access Policy Service ABAC JSONB blobs (not composable)
- Tenant Service branding fields (no inheritance chain)
- No formal role inheritance (each service duplicated role logic)
2. Migration Phases
Phase 0 — Bootstrap (Pre-service)
| Task | Owner | Notes |
|---|
| Create and deploy config-service with DB migrations | Platform team | GLOBAL node + system roles seeded |
| Import existing role definitions from identity/access-policy | Data migration script | Map legacy role codes to new RoleDefinition rows |
| Import existing feature flags from platform-admin-service | Data migration script | Create FeatureDefinition + CONFIG_NODE (FEATURE type) |
| Import tenant branding as DesignTokens | Data migration script | Tenant primaryColor, logoUrl → brand.primary, brand.logo tokens |
Phase 1 — Parallel Run
| Task | Owner | Notes |
|---|
| Services call both old pattern AND config-service | Service owners | Compare results; alert on discrepancy |
| Frontend continues using existing guards | Frontend team | No user-visible change |
| Monitor resolution latency vs. SLO | SRE | Validate p95 < 100 ms in production traffic |
Phase 2 — Cutover (Tenant by Tenant)
| Task | Owner | Notes |
|---|
| Enable config-service resolution for Pilot Tenant | Platform team | Shadow mode first; cutover on approval |
| Migrate UI element definitions for pilot tenant | Frontend team | Register all UI elements in ui_definitions |
Enable includeUI=true for pilot tenant frontend | Frontend team | Replace hardcoded guards with UIElementConfig |
| Monitor for unexpected denials | SRE | Alert on denial spike > 2x baseline |
| Expand to all tenants iteratively | Platform team | One tenant per sprint |
Phase 3 — Legacy Deprecation
| Task | Owner | Notes |
|---|
| Remove ad-hoc feature flag checks from frontend | Frontend team | After all tenants migrated |
| Deprecate individual permission call pattern from services | Service owners | Replace with GET /internal/config/resolve |
| Remove legacy branding from tenant-service API responses | Tenant team | Config-service tokens take precedence |
3. Rollback Plan
| Phase | Rollback action |
|---|
| Phase 0 | Drop config-service DB schema; no other services affected |
| Phase 1 | Disable config-service calls; services revert to old pattern |
| Phase 2 per tenant | Feature flag in platform-admin disables config-service for that tenant; old guards re-activate |
| Phase 3 | Revert frontend and service code; re-enable legacy branding fields |
4. Data Migration Scripts
| Script | Purpose |
|---|
scripts/migrate-roles-from-iam.ts | Read roles from identity-service API; create RoleDefinition + inheritance rows |
scripts/migrate-feature-flags.ts | Read feature flags from platform-admin-service; create FeatureDefinition + ConfigNode rows |
scripts/migrate-tenant-branding.ts | Read primaryColor, logoUrl from tenant-service; create DesignToken rows |
scripts/validate-migration.ts | Run parallel resolution comparisons; report discrepancies |
5. Open Questions