Migration playbook¶

Scope and philosophy¶

Every bank migration is different. The source system — whether Silverlake Symmetry, Temenos T24/Transact, Ultracs, Fiserv DNA, FLEXCUBE, or a bespoke AS/400 — has its own data model, business rules, account nomenclature, and decades of accumulated edge cases. A "build-once, run-everywhere" migration tool does not exist in practice; attempts to build one routinely underestimate this complexity and produce brittle, high-risk migrations.

This playbook defines the standard methodology for migrating a client bank onto this platform. The methodology is engagement-based: each migration is an AI-assisted consulting engagement, scoped and executed with dedicated delivery capacity. The platform provides standard integration points (the Migration API), tooling for reconciliation and validation, and a run book template. The consulting team provides source analysis, data mapping, transformation design, and cutover management — tailored to each client's specific system.

Migration API¶

The platform exposes a set of idempotent bulk-import endpoints that form the technical interface for any migration, regardless of source system. All migration data enters the platform through these endpoints.

Endpoint	Purpose
`POST /migrate/v1/customers/batch`	Bulk-import customer records (personal, KYC status, CDD tier)
`POST /migrate/v1/accounts/batch`	Bulk-import account definitions (product type, status, open date)
`POST /migrate/v1/balances/batch`	Import opening balances as day-zero ledger postings
`POST /migrate/v1/transactions/history`	Import historical transaction data for statement continuity
`POST /migrate/v1/mandates/batch`	Import direct debit mandates and standing orders
`POST /migrate/v1/loans/batch`	Import loan schedules, rate periods, security records
`POST /migrate/v1/cards/batch`	Import card records (PAN tokenisation handled by platform HSM)
`POST /migrate/v1/documents/batch`	Import KYC documents to the document vault (MOD-073)
`GET /migrate/v1/reconciliation/report`	Retrieve reconciliation report comparing imported vs. source totals
`POST /migrate/v1/kyc/import`	Import existing KYC assertion records with source bureau reference

All endpoints are idempotent: repeating a batch import with the same records produces no duplicates. Batches are identified by a client-supplied batch_reference. Failed records within a batch are quarantined with a structured error — the batch does not fail as a whole.

Phase 1 — Source system analysis¶

Duration: 4–8 weeks. Lead: AI-assisted analysis + senior consultant.

This is the most critical and variable phase. The goal is to fully understand the source system's data model and produce a validated mapping to the platform's schema.

Activities:

AI-assisted schema discovery. Feed source system data dictionaries, ER diagrams, and sample extract files to the AI analysis tooling. The AI produces a candidate entity map — source table/field → platform field — flagging ambiguities and gaps. This is a starting point, not a finished mapping.
Business rule extraction. Interview source system SMEs (typically 3–5 people: core banking admin, compliance officer, operations lead). Document all implicit rules not visible in the data: fee calculation logic, interest accrual methods, overdraft behaviour, account state transitions, special account types.
Data quality assessment. Run automated profiling on source data extracts. Common findings: duplicate customer records (same person across multiple legacy customer IDs), orphaned accounts (no customer record), dormant accounts with no activity for 7+ years (regulatory retention obligations), partially migrated data from a previous system change.
Gap identification. Identify source data elements that have no equivalent in the platform schema. Common gaps: proprietary product codes with no direct equivalent, legacy interest rate structures, historical waiver records. Each gap requires a documented decision: transform and map, discard (with client sign-off), or flag for manual review post-migration.
Mapping specification. Produce a formal data mapping specification (DMS). The DMS is a controlled document — version-controlled, client-reviewed, and signed off by the client's nominated migration owner before Phase 2 begins.

Phase 2 — Transformation design and tooling¶

Duration: 3–6 weeks. Lead: Delivery engineer + AI tooling.

Activities:

ETL pipeline build. Develop extract, transform, and load scripts specific to the client's source system. The ETL output is formatted for the Migration API endpoints. Scripts are stored in a client-specific migration repository (not this wiki repo).
Transformation validation rules. Define acceptance criteria for each data entity: customer record completeness thresholds, balance tolerance (typically zero — all balances must match exactly), loan schedule accuracy, mandate completeness. These become the automated test suite for Phase 3.
KYC import protocol. Agree the KYC assertion format with the client's compliance team. The platform accepts existing KYC status assertions if the client can supply: the verification method used, the verification date, the document types sighted, and the verifier (staff ID or third-party service reference). Where KYC records are incomplete or below the platform's minimum standard, affected customers are flagged for re-verification — either at first app login (soft re-verification) or before first transaction (hard gate, for high-risk customers).
Test environment load. Run the full ETL pipeline against a test data extract into the platform's staging environment. Review the reconciliation report. Resolve all discrepancies.

Phase 3 — Parallel run¶

Duration: 4–8 weeks. Obligation: Both systems remain live.

A parallel run is a regulatory and risk obligation, not optional. During parallel run:

All transactions processed on the source system are also applied to the platform in shadow mode.
Daily reconciliation is run comparing source system balances to platform balances.
Discrepancies are investigated and root-caused — typically revealing transformation rules that need adjustment.
Client staff use the platform UI in read-only or limited-transaction mode to build familiarity.
Any material reconciliation discrepancy must be resolved before cutover is authorised.

Go/no-go criteria for cutover: - Zero unresolved balance discrepancies for 5 consecutive business days. - Customer record completeness ≥ 99.5% (by count). - All mandatory KYC fields present for ≥ 98% of active accounts. - All direct debit mandates and standing orders validated against client source. - Client migration owner and the bank's risk owner have formally signed off in writing.

Phase 4 — Cutover¶

Duration: Typically a weekend window (Friday 6pm to Monday 6am).

Cutover sequence:

T−48h. Final source extract taken and loaded into platform staging. Reconciliation confirms zero discrepancies.
T−24h. Client communications dispatched to customers advising of the maintenance window.
T=0 (Friday 6pm). Source system frozen for new transactions. Final balance extract taken.
T+1h. Final delta load to the platform via Migration API. Opening balances confirmed.
T+2h. Automated reconciliation report run. Human review by migration lead and client representative.
T+3h. Go/no-go decision. If go: platform switched to live mode. If no-go: rollback to source system — all platform data from the cutover window is voided; source system resumes as-is.
T+4h to T+10h. Smoke test: sample transactions processed on platform. Card activation verified. Payment rails confirmed live.
Monday morning. Full business operations on platform. Source system retained in read-only archive mode for 90 days.

Phase 5 — Post-migration stabilisation¶

Duration: 30–90 days. Lead: Client success + platform operations.

Daily reconciliation continues for 30 days: platform totals vs. archived source system snapshot.
Client staff complete structured training on the platform.
Any customer complaints referencing the migration are tagged and prioritised.
KYC re-verification campaign run for flagged accounts (soft and hard gates as agreed in Phase 2).
Source system decommissioning plan agreed — typically 90 days after successful cutover.

Staffing model¶

A typical migration engagement requires the following roles:

Role	Engagement scope
Migration lead (consultant)	Full engagement — phases 1–5
AI-assisted data analyst	Phases 1–2 — source analysis and mapping
Delivery engineer	Phases 2–4 — ETL, API integration, cutover execution
Compliance reviewer	Phase 1 and 3 — KYC import protocol and parallel run oversight
Client migration owner	All phases — client-side accountable person
Platform operations	Phases 3–5 — parallel run and cutover support

The AI tooling (source schema analysis, transformation suggestion, reconciliation discrepancy triage) reduces the analyst effort in Phase 1 significantly compared to manual approaches, but does not replace the human review of AI-generated mappings. AI suggestions must be validated by an SME familiar with the source system before the mapping specification is finalised.

Common failure modes¶

Failure mode	Mitigation
Duplicate customer records not detected until post-cutover	Run deduplication analysis in Phase 1 with automated scoring; require client sign-off on deduplication rules before Phase 3
KYC records insufficient for platform minimum standard	Assess KYC completeness in Phase 1; design re-verification campaign in Phase 2; do not defer to post-cutover
Legacy interest accrual method differs from platform	Document source accrual method in DMS; calculate accrual catch-up for any difference; client sign-off required
Standing orders / direct debit mandates incomplete	Mandate completeness must be a go/no-go criterion; partial mandate migration is not acceptable
Parallel run cutover window too short	Minimum 5 business days of clean reconciliation; do not accept schedule pressure to shorten this
Source system unavailable during cutover window	Always have a rollback plan; never cut over without a tested rollback procedure