Modernisation proposal for review; durations are indicative.

Migration and Rollback

Proposal status and evidence boundary

This is an unapproved migration-and-rollback proposal for the incremental Azure modernisation described in Target Architecture and change-mapping.md. It does not approve a platform, migration, outage, staffing model, cost, service level, data transformation, retirement, or change to business behaviour.

The Modernisation Planning Summary does not establish the complete executable application, deployed schema, production topology, active interfaces, callers, integrations, data quality, authorization enforcement, transaction behaviour, operational ownership, or recovery capability. Missing, malformed, truncated and contradictory evidence must be resolved rather than converted into migration assumptions. Processing and test coverage are not proof of semantic completeness.

Existing business behaviour remains a compatibility constraint until characterized and explicitly accepted. This includes routes, request and response shapes, status codes, validation messages, localized text, nullability, ordering, persistence timing, audit intent, event timing, filenames, document layouts, report structures, navigation, lifecycle meanings and differences among import, export and transit workflows.

Migration principles

Migration should proceed through small, independently verifiable slices rather than a single replacement. Each slice must identify its authoritative system, affected users and consumers, preserved and changed contracts, data transformation, reconciliation method, activation mechanism, cutover gates, recovery path and retirement conditions.

The initial target should follow the incremental modular direction in Target Architecture. Azure App Service is the preferred initial hosting candidate only if executable-baseline recovery confirms runtime compatibility. Azure Container Apps remains an alternative for container-dependent or independently scaled workloads, and Azure SQL Managed Instance remains a coexistence option where instance-scoped SQL dependencies prevent an initial move to Azure SQL Database. Platform selection is a gate, not a migration assumption.

Uncontrolled dual writing should be avoided. During coexistence, one system must remain authoritative for each business capability and record. Compatibility adapters, controlled replication, change capture, read-through routing or shadow comparison may be used where their ordering, latency and failure behaviour are understood. If temporary dual writing is unavoidable, writes require durable correlation, idempotency, explicit partial-failure handling and scheduled reconciliation.

Rollback is appropriate only while target changes can be reversed without losing or misrepresenting accepted business activity. Once target-only writes, identities, files, events or data meanings cannot be represented safely in the legacy system, recovery must proceed forward from retained source evidence and checkpoints.

Preconditions and discovery

The first slice should implement Recover the Executable and Operational Baseline and Establish Compatibility Characterization without intentionally changing business behaviour. It should establish a reproducible build and deployment, runtime and operating-system dependencies, database provider and applied migration state, configuration sources, active routes and middleware, background work, file stores, integrations, deployment topology, monitoring, backup arrangements and operational contacts.

A complete interface inventory is required for interactive routes, service APIs, scheduled processes, reports, exports, files, documents, email, payment, identity, scanning, conversion and external company services. Unknown callers remain a cutover blocker for affected interfaces.

Data profiling must precede schema constraints and destructive changes. Profiling should cover nulls, duplicates, orphans, invalid references, status combinations, multiple approved guarantees, party and facility cardinalities, route ordinals, obsolete and sentinel reference values, units, decimal precision, collation, whitespace, business-key uniqueness, historical lookup identities and records excluded by joins.

Accountable decisions are required for contradictory or incomplete contracts, particularly submitted versus awaiting-payment semantics, receipt and rejection precedence, partial-rejection completion, guarantee cardinality, notification and shipment identifiers, working-day and consent rules, quantity conversion and rounding, pricing precedence, refund semantics, facility and treatment-site cardinality, report freshness, identity lifecycle and authorization scope. Migration must preserve unresolved distinctions rather than normalizing them.

Release sequence

The foundation release should establish deployment automation, Azure telemetry candidates, correlation, configuration controls and a representative end-to-end characterized path. It should also demonstrate backup restoration and deployment recovery in a non-production environment.

Security and transaction releases should implement the changes described by Implement Centrally Testable Authorization Policies, Centralize Authoritative Party and Relationship Checks, and Strengthen Transaction, Concurrency and Audit Boundaries. Activation should occur per bounded action only after current access outcomes have been characterized. Authorization changes must fail closed according to an accepted contract and must not rely on a general rollback flag that could restore known unsafe behaviour.

Integration and file releases should implement Introduce Durable Integration Delivery and Secure Uploads, Downloads and Generated Documents. Database changes and integration intent should use a transactional outbox where applicable. Existing synchronous responses must remain synchronous where callers depend on them. File migration to private Azure Blob Storage should preserve authoritative relational ownership, filenames, versions and authorization. Quarantined, clean, virus, unknown and error outcomes require accepted handling before activation.

Domain releases should address notification and assessment, movement and shipment, parties and locations, routes and classification, finance and pricing, guarantees, documents, and reporting as separate migration slices. Import, export and transit asymmetry must remain intact. Reporting and document replacement should follow automated comparison of current and proposed outputs.

Data movement to an Azure SQL option should occur only after SQL compatibility, stored procedures, cross-database dependencies, provider-specific behaviour and operational requirements are confirmed. Database-per-service separation is not an initial migration objective.

Data migration and reconciliation

Every migration slice requires a versioned transformation specification written in business terms. It should define source fields and meanings, target fields and meanings, deterministic mapping rules, preservation of obsolete values, timezone and date treatment, unit and precision treatment, duplicate-survivor rules, rejected-record handling, preconditions, checkpoint boundaries and rerun behaviour.

Source data should be retained unchanged for the agreed recovery and audit period. Invalid or ambiguous records must be quarantined with reasons rather than silently corrected, truncated, deduplicated, reclassified or discarded. Heuristic shipment-quantity conversion must not be accepted without an authoritative rule.

Reconciliation should include source-to-target counts by meaningful category, business-key matching, referential integrity, lifecycle invariants, status-history continuity and party relationships. Financial and quantity totals should be compared only where units, precision, currency, sign and business meaning make aggregation valid. Reconciliation should also cover payments and refunds, guarantee histories, route ordering, files and metadata, audit history, outbox delivery, reports and generated documents.

Differences must be classified as expected transformations, accepted defects, source anomalies, target defects or unresolved discrepancies. Aggregate equality alone is insufficient because offsetting errors can conceal record-level loss. Acceptance requires both automated checks and risk-based sampling by accountable business and data owners.

Coexistence controls

Routing should be controlled by capability, actor group or explicitly identified record cohort. Feature flags may separate deployment from activation, but flags affecting authorization, lifecycle meaning, calculations or data authority require restricted administration, audit, tested defaults and removal dates.

Compatibility adapters should preserve existing route shapes, status codes, messages, ordering and null handling until consumer transition is accepted. Shadow reads or calculations may compare legacy and target results without exposing target output to users. Shadow processing must not create external effects, duplicate payments, allocate identifiers, send correspondence or mutate authoritative records.

Replication lag, failed captures, duplicate events and out-of-order updates must be observable. A reconciliation queue should identify records requiring review. Coexistence must not leave users uncertain about which system owns a record or permit concurrent edits without an accepted conflict policy.

Rehearsals

At least one production-like rehearsal is required for each materially different migration pattern, followed by a full cutover rehearsal before production activation. Rehearsals should use representative, appropriately protected data and the same deployment, migration, verification and recovery procedures intended for production.

A rehearsal should test preflight failure, migration interruption, checkpoint restart, rerun safety, rejected records, reconciliation failure, deployment rollback, database restoration, message replay, dead-letter handling, file transfer interruption, scanner outage, external dependency timeout, report divergence and document comparison. Concurrency, stale requests, repeated submissions and writes occurring near the cutover boundary must also be exercised.

The rehearsal record should capture human effort, automated-agent runtime, supplier waiting time, elapsed calendar time, data throughput, discrepancy classes and recovery duration. These observations should drive re-estimation; they must not be treated as committed production performance until representative conditions are demonstrated.

Cutover plan and gates

Before cutover, the change authority must confirm the approved scope, authoritative system, consumer inventory, support coverage, communications, change-freeze rules, permitted downtime, backup and restore evidence, monitoring, runbooks, credentials, supplier availability and rollback decision authority. Business calendars, statutory or operational deadlines and high-risk transaction periods must be considered.

Technical entry gates include successful deployment and migration rehearsals, accepted compatibility tests, clean preflight diagnostics or explicitly accepted exceptions, validated backups, demonstrated restore, adequate target capacity based on measured demand, healthy dependencies, operational dashboards and no unresolved high-impact reconciliation defect.

Security entry gates include an accepted action-resource authorization matrix for the affected scope, tested denial paths, least-privilege service access, protected secrets, audit visibility and confirmed upload and download authorization where files are involved.

Cutover should establish a write boundary, drain or account for in-flight work, record migration checkpoints, apply deterministic transformations, reconcile the migrated cohort, enable target routing gradually and observe defined user journeys before expanding exposure. Queued messages, scheduled jobs, caches, files and reports must be coordinated with the same authority boundary.

No fixed observation duration or error threshold is supplied. Accountable owners must approve measurable thresholds before cutover for reconciliation differences, failed requests, latency, dependency errors, queue age, file failures, authorization denials and support incidents.

Rollback and forward recovery

Rollback triggers should be approved before activation and tied to measurable conditions. Candidate triggers include unexplained data loss or corruption, authorization bypass, incorrect financial outcomes, lifecycle transitions that cannot be reconciled, material interface incompatibility, inability to process a critical journey, uncontrolled duplicate effects, sustained dependency failure or inability to observe system state.

Application-only rollback may restore the previous deployment when schemas and contracts remain backward compatible and no target-only writes have occurred. Database rollback may use transaction reversal, checkpoint restoration or point-in-time recovery only after accounting for valid writes created after the recovery point. Restoring a database must not silently discard accepted business activity.

Where target writes occurred, rollback requires reverse mapping and reconciliation before legacy write authority can resume. If target records, identities, event history, file states or semantics cannot be represented safely in the legacy model, the plan must use forward recovery: stop or restrict affected processing, retain evidence, correct code or data deterministically, replay idempotent work, reconcile external effects and resume through an approved checkpoint.

External effects require separate treatment. Sent email, payment instructions, downloaded documents and messages consumed by third parties cannot be undone by database restoration. Compensation must be business-approved, traceable and distinguished from technical rollback. Message replay requires duplicate-tolerant consumers and explicit replay authority.

Security defects should normally be contained by disabling the affected capability, revoking access or routing to a known-safe path rather than broadly restoring weaker authorization. Evidence and audit records must be preserved throughout recovery.

Retirement conditions

A legacy capability may be retired only after all affected callers and scheduled work have moved or been explicitly closed; the target has completed an accepted observation period; reconciliation is complete; outstanding rejects and discrepancies have owners; rollback or forward-recovery obligations are satisfied; and operations has accepted monitoring, support and incident runbooks.

Retirement also requires preservation or migration of audit history, documents, reports, reference meanings and records needed for retention, legal hold, investigation or reproduction. Backup restorability and read access to retained history must be demonstrated. Credentials, network routes, jobs, replication, feature flags, licences and supplier arrangements should be removed only after dependency verification.

Legacy schemas and files must not be destructively removed merely because target processing is active. Destruction requires approved retention and deletion rules, confirmed recovery independence and evidence that downstream consumers no longer depend on the material.

Measures, scenarios and approval

Benefits cannot be claimed until baselines and targets are approved. Migration measures should include reconciliation differences, rejected records, restore-test success, recovery duration, failed-change rate, queue and dead-letter age, compatibility-test outcomes, authorization-test coverage, migration rerun success and incidents attributable to coexistence. Each measure requires an owner, source, calculation method, sampling period, baseline and target.

Low, central and high delivery scenarios cannot yet be responsibly quantified. After the first accepted slice, scenarios should be produced from observed human effort, automated-agent runtime, supplier and reviewer waiting time, environment contention and elapsed calendar time. They should expose assumptions about scarce business decision-makers, security reviewers, database specialists, operations staff and shared integration environments.

The current critical path runs through executable-baseline recovery, interface and identity discovery, domain-contract decisions, authorization mapping, data profiling, Azure compatibility validation, external dependency access and demonstrated restore and reconciliation. Production migration remains unapproved until these dependencies and the architecture approval gates in Target Architecture are satisfied.