Communication Service — Migration Plan
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · ADR-0047
1. Scope
Consolidate legacy messaging service (COM-MSG) + virtual-care service + ad-hoc notification code paths into the unified communication-service.
2. Phases
| Phase | Scope | Milestone |
|---|---|---|
| P0 — Route duality | /v1/communication/* added as canonical; /v1/digital-communication/* and /v1/messaging/* remain as aliases | M1 |
| P1 — Event dual publish | Canonical ghasi.digital_communication.* published in parallel with legacy ghasi.messaging.* and VIRTUAL_CARE.* | M1 |
| P2 — Schema unification | Merge messaging + virtual-care schemas into communication schema; legacy tables read-only | M2 |
| P3 — Consumer migration | All downstream services subscribe to canonical subjects; legacy consumers stopped | M3 |
| P4 — Alias sunset | Remove legacy routes + legacy events + legacy tables | M4 |
3. Data migration
| Source | Target | Strategy |
|---|---|---|
messaging.threads | communication.message_threads | Backfill by tenant_id; preserve IDs; add node_id when null |
messaging.messages | communication.messages | Stream copy with ordering by sent_at; verify checksums |
messaging.read_receipts | communication.message_read_receipts | Direct copy |
messaging.attachments | communication.message_attachments | Copy metadata; rescan AV if older than 90 days |
virtual_care.sessions | communication.virtual_sessions | Copy; state map to new enum |
virtual_care.participants | communication.virtual_participants | Copy |
| Notification stubs (various) | communication.notification_intents | Build from historical audit; optional - can forward-only |
4. Event migration
| Old subject | New subject | Dual-publish |
|---|---|---|
ghasi.messaging.sent | ghasi.digital_communication.message.sent | Until M3 |
ghasi.messaging.read | ghasi.digital_communication.message.read | Until M3 |
VIRTUAL_CARE.session.created | ghasi.digital_communication.virtual_session.created | Until M3 |
portal.notification.queued (consumed) | unchanged | — |
SCHEDULING.appointment.created (consumed) | unchanged | — |
5. Tenant rollout
- Shadow period (2 weeks per tenant): both old and new services run; new service publishes dual events but responses come from old paths — used to verify data parity.
- Flip: canonical routes become primary; old routes reverse-proxy to new service.
- Observation: 30-day monitoring for SLO parity, error-rate parity.
- Decommission: legacy service stopped and DB dropped after 60-day retention.
6. Backout plan
- Kong route swap is reversible in < 5 minutes.
- Legacy service retained (scaled to zero) through P4; can be scaled back on rollback.
- Data migration is copy, not move; legacy tables preserved until P4 GA.
7. Risks during migration
| Risk | Mitigation |
|---|---|
| Duplicate events during dual-publish | Consumers keyed off canonical types; legacy aliases deduped by correlation id |
| Thread ID collision | Preserve IDs; namespace prefix thr_ was already unique |
| Notification lost between systems | Sequence-preserving forward queue; reconcile report |
| User-visible latency regression | Canary per tenant; rollback on p95 degradation |