Skip to main content

Platform Admin Service — Migration Plan

Status: populated Owner: TBD Last updated: 2026-04-18

1. Migration scope​

platform-admin-service is a new service extracting functionality previously scattered across:

Legacy locationNew homeNotes
Monolith platform-config moduleplatform-admin-service PlatformConfigSchema normalized; allow-list enforced
Monolith feature-flags moduleplatform-admin-service FeatureFlagEvaluation logic extracted; Redis cache standardized
Ad-hoc health endpointsplatform-admin-service HealthSourceDynamic registration replaces hardcoded list

2. Legacy FR mapping​

Legacy prefixNew prefix
FR-ADM-CFG-*FR-PLTADM-CFG-*
FR-ADM-FF-*FR-PLTADM-FF-*
FR-ADM-HLT-*FR-PLTADM-HLT-*
FR-ADM-ENH-*FR-PLTADM-ENH-*

3. Migration phases​

Phase 1 — Config extraction (M0)​

  1. Create platform_admin schema; run migrations.
  2. Export existing config KV from legacy monolith table.
  3. Validate all keys against code allow-list; log unknown keys for review.
  4. Deploy platform-admin-service; route /admin/platform-config from monolith.
  5. Verify config reads produce consistent results.

Phase 2 — Feature flag extraction (M0)​

  1. Export existing feature flags from legacy module.
  2. Migrate tenant override arrays to new schema.
  3. Validate evaluation logic parity (test 50 sample flag+tenant combinations).
  4. Route evaluate endpoint from services to /internal/admin/flags/:key/evaluate.
  5. Legacy evaluate endpoint remains in monolith behind compatibility header for 30 days.

Phase 3 — Health source migration (M1)​

  1. Replace hardcoded health endpoint list with dynamic registration.
  2. Update each service's startup to call POST /internal/admin/health/sources.
  3. Verify aggregate health reflects all 27 services.
  4. Remove legacy health aggregation from monolith.

Phase 4 — Compatibility route sunset (M2/M3)​

  1. Remove legacy /api/platform/* compatibility routes after 30-day verification.
  2. Update any clients still using legacy paths.

4. Rollback plan​

PhaseRollback
Phase 1Feature flag PLTADM_SERVICE_CONFIG_ENABLED=false re-routes to monolith
Phase 2Evaluate compatibility route kept; monolith flag eval remains active
Phase 3Hardcoded source list re-enabled via config flag

5. Open questions​

  • Are there any tenant-scoped config keys in the legacy system not in the current allow-list?
  • Feature flag migration: which flags are currently active and must not be interrupted?