Document Service — Migration Plan
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template
1. Migration Context
The document-service supersedes the legacy "DMS" module embedded in the ghasi-ehr monolith. Legacy document handling was fragmented:
- PDF generation was client-side in some modules (PHI exposure risk)
- Template definitions were stored in unversioned JSONB blobs
- No virus scanning on uploads
- FHIR DocumentReference was created inconsistently or not at all
- No unified audit trail for document access
2. Migration Phases
Phase 0 — Bootstrap
| Task | Owner | Notes |
|---|---|---|
| Deploy document-service with DB migrations | Platform team | No tenants migrated yet |
| Seed platform reference templates | Platform team | General Test Requisition + other platform forms |
| Configure object storage buckets + KMS keys | Platform team | Separate buckets per region |
| Configure ClamAV | Platform team | Virus definition update schedule set |
Phase 1 — Template Migration
| Task | Owner | Notes |
|---|---|---|
| Export legacy template definitions from monolith | Data engineering | Extract template JSONB blobs |
Transform to DocumentTemplateVersion.definition schema | Data engineering | Map layout + binding fields |
| Import as draft versions | Data migration script | pnpm migration:import-templates |
| Clinical review and publish | Clinical informatics | Each tenant signs off on migrated templates |
Phase 2 — Document Artifact Migration
| Task | Owner | Notes |
|---|---|---|
| Export legacy PDF artifacts from monolith storage | Data engineering | Tenant-scoped paths |
Copy to new object storage layout /{tenantId}/documents/ | Data migration script | Via S3 copy API |
Create DocumentReference + Binary FHIR resources for each | Data migration script | pnpm migration:create-fhir-refs |
| Validate migrated DocumentReference list | Clinical informatics | Spot-check per tenant |
Phase 3 — Cutover
| Task | Owner | Notes |
|---|---|---|
| Route generate / upload calls to document-service | Kong routing change | Feature flag per tenant |
| Disable legacy document generation in monolith | Engineering | After document-service validated for tenant |
| Migrate document access audit trail | Audit team | Historical records imported to audit-service |
| Validate audit completeness | Compliance | HIPAA accounting of disclosures check |
Phase 4 — Legacy Deprecation
| Task | Owner | Notes |
|---|---|---|
| Remove legacy DMS module from monolith | Engineering | After all tenants migrated |
| Archive legacy PDF storage (legal hold) | SRE | Keep per retention policy; mark as archived |
3. Rollback Plan
| Phase | Rollback action |
|---|---|
| Phase 0 | Drop document-service DB schema and object storage buckets; no tenants affected |
| Phase 1 | Re-import templates; no production traffic yet |
| Phase 2 | Remove newly created FHIR resources; restore from legacy storage backup |
| Phase 3 per tenant | Feature flag disables document-service for that tenant; route back to monolith |
| Phase 4 | Restore monolith DMS module from backup; re-enable legacy routing |
4. Data Migration Scripts
| Script | Purpose |
|---|---|
scripts/migration/import-templates.ts | Import legacy template JSONB blobs as DocumentTemplate + DocumentTemplateVersion rows |
scripts/migration/copy-artifacts.ts | Copy legacy PDF blobs to new object storage layout |
scripts/migration/create-fhir-refs.ts | Create DocumentReference + Binary for migrated artifacts |
scripts/migration/validate-migration.ts | Verify document count + spot-check metadata per tenant |
scripts/migration/seed-platform-templates.ts | Import platform reference template catalog |
5. Open Questions
- Agreed priority order for tenant template migration (which tenants first).
- Retention policy for legacy monolith PDF storage after migration (legal hold duration).