How to migrate existing systems to the Engineering Architecture & Data Flow Guideline: test-first, incremental approach with baseline → tests/contracts → migrate → sign-off. Migration matrix tracks progress; contract tests guard behaviour; CI runs tests on every push.
This document describes how to migrate existing systems to adopt the Engineering Architecture & Data Flow Guideline. It is a companion to that guideline: the guideline defines the target state; this document defines a repeatable, low-risk migration process.
Outcome
Teams can adopt the architecture incrementally, with tests guarding behaviour and a clear checklist so humans or AI can continue from the last completed step.
The patterns below apply to any web application, API, service, or integration you want to migrate to the target architecture.
Optional: understand Asana usage for tracking migration work
Scope
Applies to: Existing web applications, APIs, microservices, or integrations that will be refactored to match the Engineering Architecture & Data Flow Guideline.
Does not replace the guideline; it defines the process for getting from current state to the guideline’s target state.
Does not prescribe languages, frameworks, or deployment tools; it prescribes phases (baseline → tests/contracts → migrate → sign-off) and how to track progress.
Definitions
Term
Definition
Migration unit
One endpoint, one route group, or one cohesive feature that can be migrated and tested independently (one row in the migration matrix).
Contract test
A test that asserts request/response shape and HTTP status for an endpoint (e.g. happy path, validation error, not found, server error). Used to lock current behaviour before refactoring.
Migration matrix
A table whose rows are migration units (endpoints) and whose columns are: DTO defined, contract tests (happy / 4xx / 5xx), tests in CI, migration done. Used to track progress and resume work.
DTO (contract)
Data structure defining an external boundary (request or response payload). See the main guideline for Contract / DTO.
Migration Strategy (Overview)
Principle
1
Test-first: Lock current behaviour with contract tests (and optional DTOs), then refactor. Tests must pass before and after each migration step.
2
Incremental: Migrate one endpoint (or one migration unit) at a time. After each step, all tests stay green.
3
Contracts explicit: When writing tests, define request/response DTOs so boundaries are clear from the start.
4
Track in a matrix: Rows = endpoints (or units), columns = DTO, tests, CI, migration done. Enables handoff and “continue from last completion.”
Outcome
Safe, reviewable changes; no big-bang rewrite; behaviour preserved by tests.
Step-by-Step Migration Process
Phase 1 — Baseline
Step
Action
1
List all endpoints (or route groups) that will be migrated. Treat each as one migration unit (one row in the matrix).
2
Create the migration matrix (see Migration Checklist (Tracking)). Optionally keep it in the repo (e.g. docs/migration-checklist.md) or in Asana.
3
Optional but recommended: Introduce cross-cutting pieces once (e.g. standard error shape { code, message, details? }, correlation ID middleware, entry-point logging). New and migrated code can then use them consistently.
Phase 2 — Tests and Contracts
Step
Action
1
For each migration unit (or in a batch): define request/response DTOs (contracts) and write contract tests against the current implementation. Tests assert: happy path (status + response shape), validation/4xx, and error/5xx where relevant.
2
Run the test suite until all new contract tests pass on the existing (pre-refactor) code.
3
Commit the tests (and DTOs). Wire the test suite into CI (e.g. Git → GitHub → your deployment pipeline). Ensure every push runs the tests.
4
Do not start refactoring until Phase 2 is complete and CI is green.
Phase 3 — Migrate
Step
Action
1
Pick the simplest migration unit first (e.g. one GET with a single resource and clear input/output). Use it to establish the pattern.
2
For that unit: refactor to Entry point → Application logic → Data access. Entry: parse/validate, DTO ↔ entity, call application logic, map errors to standard shape. Application logic: business rules and orchestration using entities only. Data access: repositories/adapters, entity ↔ storage/external only.
3
Run the full test suite. All tests must remain green. Update the matrix (e.g. mark “Migration done” for that row).
4
Repeat for the next migration unit. Prefer migrating simpler endpoints before complex ones (e.g. leave multi-system orchestration or streaming endpoints for later).
5
Continue until every row in the matrix that is in scope is marked “Migration done.”
Document any exceptions or follow-up items (e.g. ADR or short note).
Migration Checklist (Tracking)
Use a matrix so that any human or AI can see what is done and continue from the last completion.
Matrix columns (suggested)
Column
Meaning
Endpoint / Unit
Route or feature name (e.g. GET /resource/:id).
DTO defined
☐/☑ Request and response contracts exist and are used in tests.
Contract test (happy)
☐/☑ Happy-path status and response shape covered.
Contract test (validation / 4xx)
☐/☑ Validation and client-error paths covered.
Contract test (5xx / error)
☐/☑ Server-error or error-response shape covered where applicable.
In CI
☐/☑ Tests run in the pipeline on every push.
Migration done
☐/☑ Refactored to Entry → Application logic → Data access; all tests green.
Example matrix (template)
Endpoint
DTO defined
Contract test (happy)
Contract test (4xx)
Contract test (5xx)
In CI
Migration done
GET /
☐
☐
☐
☐
☐
☐
GET /resource/:id
☐
☐
☐
☐
☐
☐
GET /items
☐
☐
☐
☐
☐
☐
POST /items
☐
☐
☐
☐
☐
☐
…
☐
☐
☐
☐
☐
☐
Keep the matrix in your repo (e.g. docs/migration-checklist.md) or in Asana; update it as each step is completed.
CI/CD and Safety
Rule
1
Tests run on every push (e.g. GitHub → pipeline → report status). No migration step should be merged with failing tests.
2
Do not rely on “manual only” verification for migrated behaviour; contract tests are the gate.
3
Optional: run contract tests against a deployed environment (e.g. staging) if your pipeline supports it, to catch environment-specific issues.
Asana & Operating Model
When the migration is tracked as formal work:
Suggestion
1
Create an initiative or project in Asana (e.g. “Migration to Architecture Guideline – [System name]”). Link to this document and to the migration matrix.
2
Use the matrix to assign work: e.g. “Complete tests for row X” or “Migrate endpoint Y.”