Audit Service — Migration Plan
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template
1. Migration context
The Audit Service is built from a single source module (_sources/audit/, PLAT-AUDIT v2.0) with no multi-module consolidation required. Migration concerns are:
- Onboarding existing tenant data from any pre-v2.0 audit store (if applicable) into the new immutable schema.
- Migrating NATS subject subscriptions from legacy
com.ghasi-ehr.*subjects to canonical{service}.{aggregate}.{event}.v{N}subjects. - Ensuring new platform services emit events on both subject formats during the transition window.
2. Legacy subject mapping
The pre-v2.0 audit consumer subscribed to com.ghasi-ehr.* wildcard. Canonical subjects follow the pattern {service}.{aggregate}.{event}.v{N}. The transition is managed via dual-publish at the source services (not in the audit service):
| Legacy wildcard | Canonical equivalent | Audit impact |
|---|---|---|
com.ghasi-ehr.iam.* | identity.user.*.v1, identity.provider.*.v1 | Both ingested during transition |
com.ghasi-ehr.tenant.* | tenant.tenant.*.v1 | Both ingested during transition |
com.ghasi-ehr.hierarchy.* | facility.node.*.v1, facility.edge.*.v1 | Both ingested during transition |
com.ghasi-ehr.platform.* | platform_admin.config.*.v1 | Both ingested during transition |
patient_chart.* | Canonical only (new service) | Canonical only from M0 |
ai_gateway.* | Canonical only (new service) | Canonical only from M0 |
Deduplication on source_event_id prevents double-counting during dual-publish transition.
3. Legacy data backfill
| Scenario | Action |
|---|---|
| Pre-v2.0 audit log exists (flat JSONL or CSV) | ETL script normalises rows into AuditEntry shape; chain-hash is computed for each row; backfilled entries marked backfilled=true in metadata; chain continuity starts from first live event |
| No pre-v2.0 audit data | No backfill needed; audit trail begins from service go-live |
| Legacy audit database (PostgreSQL) | One-time export → normalise → insert script; idempotent on source_event_id |
4. Phase plan
5. Rollback plan
The audit service schema is append-only; rollback of ingested data is not applicable. If the service itself is rolled back:
| Scenario | Action |
|---|---|
| Service deploy rolled back | NATS messages accumulate in JetStream; re-delivered to next healthy pod |
| Schema migration error | Drizzle migration rolled back via pnpm db:migrate:down; no data lost (no rows inserted in failed migration) |
| Backfill script partial run | Script is idempotent; re-run completes remaining rows; no duplicates |
6. Tenant onboarding
New tenants are onboarded automatically — when a tenant's services begin emitting events, the wildcard consumer ingests them into audit_entries with the correct tenant_id. No per-tenant configuration is required in the audit service.
7. Open questions
- Confirm whether any pre-v2.0 audit data exists and needs backfill (depends on whether pilot tenants have legacy audit logs).