Skip to main content

Number Intelligence Service — Migration Plan

Version: 1.0 Status: Draft Owner: Messaging Core Last Updated: 2026-04-20

1. Intent​

This document describes how legacy data and existing tenants migrate into number-intelligence-service. Today MSISDN attribution is implicit in routing-engine's prefix table and ad-hoc heuristics. This service replaces that with an authoritative model fed by live HLR + MNP + EIR.

2. Pre-Conditions​

TBD

  • Per-MNO HLR endpoints contracted and tested
  • Per-MNO MNP feeds contracted and tested
  • ATRA EIR feed contracted and tested
  • Postgres ni schema migrated
  • Redis cluster provisioned

3. Migration Phases​

TBD

Phase 1 — Shadow mode​

  • NI deployed and serving ResolveMsisdn to no production caller
  • routing-engine calls NI in shadow mode and compares to its prefix table
  • Discrepancies logged for analysis

Phase 2 — Co-existence​

  • routing-engine uses NI as primary, prefix table as fallback
  • sms-firewall-service migrated to NI for origin attribution
  • Initial backfill: bulk-prime ni.msisdn_attribution from observed traffic over 7 days

Phase 3 — Cutover​

  • NI authoritative; prefix table retired in routing-engine
  • Public Lookup API GA'd to selected tenants
  • Per-MNO TPS contracts ramp to production levels

4. Backfill Strategy​

TBD

  • Mass-prime via observed CDR traffic for 7 d (no live HLR cost)
  • MNP registry seeded from initial full file from each MNO
  • EIR seeded from initial full file from ATRA

5. Rollback Plan​

TBD

  • routing-engine re-enables prefix table (kept dormant for 90 d)
  • NI continues to ingest reconciliation files; only the routing decision changes

6. Tenant Migration​

TBD

  • Public Lookup API rolled out to opt-in tenants in waves
  • Existing tenants automatically get internal NI enrichment with no API changes

7. References​

  • ADR-0004 §3
  • SERVICE_OVERVIEW.md §11