Migration Readiness

Status

Active

Date

2026-04-28

Owners

• Platform Backend

Last Verified Commit

def491e5

Goal

Track whether servers_v2 can replace the legacy servers/ runtime without user-visible or external-integration-visible regressions.

Current Decision

servers_v2 is ready for slice-based cutover in several areas, but it is not yet ready for a full one-shot replacement of the entire servers/ tree.

Readiness Matrix

Legacy Scope	servers_v2 Replacement	Current State	Evidence
web_server player routes	gateway + domain services	ready for controlled cutover	gateway route parity review and contract tests
agent_server	agent_service	ready for controlled cutover	route parity review and test_agent_integration.py
game_server	game_service	ready for controlled cutover	route parity review and test_legacy_contracts.py
middle_server recon slice	recon_service + admin_service top-info aggregation	ready for controlled cutover	recon service routes, admin top-info aggregation tests, local Docker validation
middle_server web CMS slice	removed by ADR-009; callers must migrate or retire	not ready	legacy web routes were deleted from admin_service
wallet_server split domain behavior	wallet_service + rolling_service + promotion_service	operationally strong, but depends on caller cutover	worker and contract tests
whole legacy back-office sidecar scope	partially admin_service, partially unmapped	not ready	docs/runbooks/legacy-middle-server-retirement.md (per-prefix migration plan); 410-Gone + Sunset stubs in servers_v2/admin_service/app/api/routes/legacy_sunset.py fail loud for any forgotten caller

What Is Already Strong

• player-facing gateway compatibility is documented and covered by route contract tests
• agent-facing compatibility exists with zero old-only route gaps in the current comparison
• provider callback surface exists with zero old-only route gaps in the current comparison
• recon extraction is now documented, implemented, workerized, and locally Docker-tested
• admin top-info can aggregate recon counts without reintroducing the deleted legacy recon route surface
• worker health and settlement semantics now align with production expectations better than the legacy stack

What Still Blocks Full Legacy Retirement

The main blocker is not the player, agent, or provider path. It is the remaining middle_server scope that still has active or potentially active frontend callers:

• /api/admin/role/*
• /api/admin/menu/*
• /api/admin/config/*
• /api/admin/i18n/*
• /api/admin/bi/*
• /coin/*
• generic catch-all forwarding behavior from legacy POST /{path:path}

/api/admin/web/* was previously not a blocker as of the 2026-04-22 admin compatibility migration; under ADR-009 (2026-04-27) the legacy web content compatibility surface (legacy_web_content.py) is deleted together with the rest of the staff-coupled legacy files. Any bo/admin consumer that still depends on /api/admin/web/rules/*, /api/admin/web/faq/*, or /api/admin/web/config/* must be migrated or retired before that deletion lands.

Compatibility evidence for this slice:

• servers_v2/admin_service/tests/test_admin_integration.py
• docs/runbooks/legacy-middle-server-retirement.md — per-prefix migration plan, owners, effort estimates, cut-over sequence
• servers_v2/admin_service/app/api/routes/legacy_sunset.py — 410-Gone + Sunset + Deprecation stubs so forgotten callers fail loud instead of silent-404
• servers_v2/admin_service/tests/test_legacy_sunset.py — guard test locking the 410 + header + auth contract so a regression cannot re-add a 200 OK to a retired prefix

Posture Summary (2026-05-06)

servers_v2 is production-ready for slice-based cutover of the following surfaces. Each item below is shipping-grade as of this posture entry — they have route parity, contract tests, and operational runbooks.

• player gateway traffic
• agent service traffic
• provider callbacks
• recon worker
• multi-brand isolation (Phase 16 hard-flip closed)

servers_v2 does NOT cover the following surfaces and they remain on the legacy servers/ runtime indefinitely:

• /api/admin/role/*
• /api/admin/menu/*
• /api/admin/config/*
• /api/admin/i18n/*
• /api/admin/bi/*
• /coin/*
• legacy back-office catch-all POST /{path:path}

There is no in-flight project to migrate the surfaces above. Any document or release announcement that claims "full replacement of the legacy servers/ tree" is incorrect and must be corrected. The honest posture is: servers_v2 plus residual servers/ middle_server slice, co-deployed.

If a future project is chartered to migrate any of these surfaces, the corresponding bullet above should be moved into the readiness matrix and this section updated to reflect the new shipping-grade scope.

Multi-Brand Migration Readiness

Per ADR-009, multi-brand isolation is implemented as a forward migration, not a separate cutover:

• a default brand is seeded at migration time and every existing row is backfilled into it via column-level DEFAULT (see plan Phase 2);
• the existing single-brand environment continues to operate against the default brand throughout every implementation phase;
• gateway JWT/domain enforcement was staged through observe mode during the rollout; the repository compose default is now enforce after the Phase 16 in-repo closure.

Multi-brand readiness is tracked separately from the legacy-cutover matrix above. A second brand is enabled only after the multi-brand runbook's release gate (docs/runbooks/multi-brand/multi-brand-isolation-rollout.md) passes.

Cutover Guidance

Safe current cutover candidates:

• player web traffic to gateway
• agent frontend traffic to agent_service
• provider callbacks to game_service
• recon shooter/pushbullet workflows to admin_service + recon_service

Do not declare full legacy replacement complete until:

1. every remaining middle_server route family is either migrated or explicitly retired
2. bo/admin no longer depends on unmapped legacy route families
3. the team chooses whether any generic forwarding behavior is intentionally removed or must be replaced explicitly
4. migration runbooks are updated to reflect the final target state