| name | migration-design |
| description | Design safe architectural migrations across data, interfaces, components, deployments, and consumers using compatibility stages, observability, rollback or forward recovery, and explicit completion criteria. |
Migration Design
Use when changing durable architecture while existing data, callers, deployments, or users must continue working through the transition.
Procedure
- Define the current state, target state, and reason for migration. Identify every durable artifact or consumer that spans the transition: data, APIs, events, files, caches, jobs, configuration, clients, services, and operational procedures.
- Identify incompatibilities between old and new states and the deployment combinations that can exist in reality. Include rolling deployments, offline clients/workers, replayed events, old persisted records, and partial completion.
- Prefer staged compatibility when practical: introduce additive support, deploy compatible readers, migrate/backfill state, switch writers/traffic, observe, then remove old paths only after evidence shows they are unused.
- For data migrations, define invariants, backfill strategy, batching, concurrency with live writes, validation, retry/restart semantics, and how failures are detected without corrupting or silently skipping records.
- For interface migrations, define version/feature negotiation, adapters or shims, deprecation signals, consumer migration order, and the condition that permits deleting compatibility code.
- Define source of truth during each stage. Dual-read/write designs require explicit conflict and reconciliation rules; avoid indefinite periods where nobody knows which representation is authoritative.
- Plan observability around migration progress and correctness: counts, mismatches, error rates, old-path usage, queue/backlog age, performance impact, and other signals that prove whether a stage is safe to advance.
- Define recovery. Use rollback where the previous state can actually be restored safely; otherwise define forward-fix or restore-from-backup/replay procedures for irreversible transformations.
- Keep the migration bounded. Give temporary adapters, flags, duplicate fields, and compatibility code owners plus removal criteria so the transition does not become permanent architecture.
- Validate the migration in a representative environment and with production-shaped data/traffic when risk warrants it before executing irreversible stages.
Decision rules
- A migration plan must cover mixed states, not only the beginning and end diagrams.
- Rollback is not real if data or external side effects become incompatible with the old version.
- Prefer additive staged change over synchronized cutover when the compatibility cost is reasonable.
- Temporary complexity is acceptable when it buys safe transition, but it needs an exit condition.
- Operational execution belongs to the implementing/operations roles; Software Architect owns the durable transition design and compatibility model.
Quality gate
The migration design is ready when current/target states and intermediate combinations are explicit, data and interface compatibility are preserved or deliberately coordinated, progress/correctness are observable, recovery matches what is actually reversible, temporary mechanisms have removal criteria, and the migration can finish without leaving two permanent architectures.
