Skip to main content

Analytics Service — Migration Plan

Status: populated Owner: Platform Engineering + SRE Last updated: 2026-04-18

1. Context​

Greenfield service. No predecessor. Migration involves:

  1. Backfilling historical analytics from NATS stream replay (up to stream retention limits).
  2. Migrating any pre-existing manual reporting (spreadsheets/ad-hoc queries) to this service's REST API.

2. Schema Migration​

Standard Prisma migrations applied in order. No complex data transformations — tables start empty and are filled by event processing.

# Staging
pnpm --filter @ghasi/service-analytics prisma migrate deploy

# Production
# Applied via CI/CD pipeline on deploy

3. Historical Backfill​

NATS streams retain:

  • BILLING_EVENTS: 7 days.
  • SMS_DLR: 3 days.

Backfill procedure:

  1. Deploy analytics service with empty DB.
  2. Seek durable consumers to the oldest available sequence: nats consumer edit BILLING_EVENTS anlyt-billing-consumer --deliver all.
  3. Service replays all retained events; processed_events dedup ensures correct single-processing.
  4. After catch-up, consumers switch to normal push delivery.

For history beyond stream retention, a data migration from the existing PostgreSQL orch.sms_messages and billing tables may be performed by a one-time backfill script. Estimate: ~3 hours for 90 days of data at expected platform scale.

4. Dashboard Cutover​

Admin-dashboard currently reads ad-hoc queries from orch schema directly. Migration plan:

  1. Deploy analytics service + seed data.
  2. Update admin-dashboard to call analytics REST API.
  3. Smoke-test dashboard accuracy vs old ad-hoc queries.
  4. Remove ad-hoc query code from admin-dashboard.

5. Rollback​

  • Analytics DB can be dropped and recreated (it is a projection — source of truth is always NATS/billing/orch schemas).
  • Admin-dashboard can revert to direct DB queries if analytics API is unavailable (feature flag).