System design · Phased project

Replace an account service one tenant at a time

A fictional B2B scheduling service stores account settings in a legacy module whose database access leaks into HTTP handlers. A replacement must support existing clients and migration by tenant. Build a local modular application, a synthetic two-tenant dataset, and controllable old/new adapters; no baseline repository or fixtures are supplied. Keep the exercise in one application and local database, with no live customer traffic.

Practice brief · Version 5

Project scope: 10 tickets / 3 phases
Total focused work estimate: 32h 30m + setup
Suggested stack: TypeScript · Node.js · PostgreSQL · Vitest

Recommended next step

Start with PMIGRATE-101

Open the first ticket for its prerequisites, acceptance criteria, verification plan, and an editable task draft.

Open first ticket Add to My work

What the engineer takes away

Practice incremental migration, dependency boundaries, compatibility testing, and removing abstractions that obscure behavior rather than enabling change.

What the team gains

Inspect a migration plan with measurable parity, explicit write ownership, tenant-safe routing, and rollback limits instead of accepting a rewrite diagram alone.

Before you start

REST contracts
Tenant authorization
Transactions
Dependency injection

Delivery agreement

Ten tickets in three migration phases. An individual ticket needs a minimal local reproduction of its legacy behavior; the full project ends with a rehearsed synthetic tenant cutover and retirement checklist.

AI tools are welcome during implementation. Record assumptions, review the result, and verify its behavior.

Delivery phases

PHASE 1
Establish a stable boundary
Capture old behavior and remove hidden tenant state before routing changes.
PHASE 2
Compare and route deliberately
Introduce the replacement without duplicate effects or unexamined abstractions.
PHASE 3
Cut over and retire
Prove write ownership, compatibility, and recovery before removing legacy paths.

Establish a stable boundary

Capture old behavior and remove hidden tenant state before routing changes.

PMIGRATE-101
Put legacy account lookups behind a contract the replacement can keep
Entry ticket; project setup still required
Estimated field mix
- API design50%
- System design30%
- Backend20%
Pattern topics
- FacadeApply
Task · Foundational · 1h 30mAdd to My work
PMIGRATE-102
Remove the process-wide current-tenant account client
Depends on PMIGRATE-101
Estimated field mix
- Security50%
- Backend30%
- System design20%
Pattern topics
- SingletonRemove
Bug · Advanced · 3h 30mAdd to My work
PMIGRATE-103
Separate account policy from legacy SQL and replacement storage
Depends on PMIGRATE-102
Estimated field mix
- System design50%
- Backend30%
- Database engineering20%
Pattern topics
- Ports and AdaptersRefactor
Story · Intermediate · 3hAdd to My work

Compare and route deliberately

Introduce the replacement without duplicate effects or unexamined abstractions.

PMIGRATE-104
Shadow account reads without duplicating booking-channel writes
Depends on PMIGRATE-103
Estimated field mix
- System design50%
- Backend30%
- Site reliability20%
Pattern topics
- Strangler FigApply
Task · Advanced · 3h 30mAdd to My work
PMIGRATE-105
Preserve tenant scope and conditional reads through the migration proxy
Depends on PMIGRATE-104
Estimated field mix
- API design40%
- Security40%
- System design20%
Pattern topics
- ProxyRefactor
Bug · Intermediate · 2h 30mAdd to My work
PMIGRATE-106
Decide whether a separate account summary read model earns its lag
Depends on PMIGRATE-103, PMIGRATE-104
Estimated field mix
- System design40%
- Database engineering30%
- Performance engineering30%
Pattern topics
- CQRSCompare
Task · Expert · 5hAdd to My work
PMIGRATE-107
Delete account facade layers that only rename the same call
Depends on PMIGRATE-101, PMIGRATE-103
Estimated field mix
- System design60%
- Backend40%
Pattern topics
- FacadeRemove
Chore · Foundational · 1h 30mAdd to My work

Cut over and retire

Prove write ownership, compatibility, and recovery before removing legacy paths.

PMIGRATE-108
Transfer tenant write ownership without accepting commands on both sides
Depends on PMIGRATE-105, PMIGRATE-106
Estimated field mix
- System design40%
- Distributed systems40%
- Database engineering20%
Pattern topics
- Strangler FigApply
Story · Expert · 5h 30mAdd to My work
PMIGRATE-109
Catch replacement-adapter drift before declaring tenant parity
Depends on PMIGRATE-103, PMIGRATE-105, PMIGRATE-107
Estimated field mix
- Quality engineering50%
- System design30%
- Database engineering20%
Pattern topics
- Ports and AdaptersApply
Task · Intermediate · 3hAdd to My work
PMIGRATE-110
Retire the legacy account path only after the last caller is accounted for
Depends on PMIGRATE-108, PMIGRATE-109
Estimated field mix
- System design50%
- Site reliability30%
- Database engineering20%
Pattern topics
- Strangler FigApply
- ProxyRemove
Chore · Advanced · 3h 30mAdd to My work