Architecture Data Migration Plan

Phase: 1 Architecture Plan Status: high-level plan; detailed runbook lives in docs/migration/data-migration-plan.md

Objective

Move data from the legacy single Prisma/Postgres database into service-owned Postgres databases without breaking current /api behavior.

Migration Modes

Mode	Use Case	Writes
Read-only audit	inventory and parity reports	none
Backfill snapshot	initial service database load	target service only
Shadow validate	compare Go reads to legacy reads	none or target staging only
Native route cutover	gateway serves Go route	target service authoritative
Legacy rollback	gateway sends route back to NestJS	legacy authoritative again

Ordering Constraints

1. Auth/user/school identity mapping before tenant-owned domain writes.
2. Document/media before DOCX import approval.
3. Question type/taxonomy before question import.
4. Questions before exam authoring migration.
5. Exam publish snapshots before attempt migration.
6. Attempt migration before analytics rebuild.

Data Integrity Rules

• Preserve legacy_id for every migrated row.
• Preserve historical JSON snapshots exactly where used for exam/attempt integrity.
• Preserve object keys for media and documents.
• Do not deduplicate or normalize question content during first backfill.
• Do not infer missing question types differently from legacy import/editor behavior.

Validation Summary

Each migration batch must report:

• source row count
• target row count
• skipped rows with reason
• orphan references
• checksum/hash for important JSON fields
• sample route parity evidence

Rollback Summary

Preferred rollback is gateway route rollback to legacy. Target service databases should be preserved after rollback for diagnosis unless corrupt data is actively harmful.