Modernisation proposal for review; durations are indicative.

change-mapping.md

This document is an unapproved change-mapping proposal. It maps evidenced capabilities and unresolved requirements to preservation, change, resolution or deferral decisions for an incremental Azure modernisation. The supplied material is a qualified synthesis rather than a complete account of the application or its production operation. Existing behaviour remains a compatibility constraint until characterization and accountable acceptance establish otherwise.

CHG-001 Recover the Executable and Operational Baseline

The evidence describes a broad application estate but does not establish the complete source, deployed schema, active routes, registrations, middleware, runtime configuration, topology, callers, scheduled work or operational controls. The decision is to resolve this evidence gap before committing to replacement architecture. The target is a reproducible build and deployment, an authoritative inventory of application and database components, and one representative end-to-end path traced through authorization, validation, persistence, audit, events, files and external effects.

This change depends on access to source, package metadata, environments, database state, configuration, logs, file stores, deployment tooling and external dependency owners. Acceptance requires demonstrated execution rather than compilation or test success alone. Runtime support, operating-system dependencies, document-conversion software, background processes, production topology and missing or malformed evidence remain uncertain.

CHG-002 Establish Compatibility Characterization

Existing routes, request and response shapes, status codes, validation messages, resource text, nullability, ordering, persistence timing, document layouts, report structures, audit intent, event timing and navigation are evidenced as potential contracts. The decision is to preserve them until callers and meanings are inventoried and an explicit change is accepted. The target is a compatibility catalogue supported by characterization and integration tests around representative successful, denied, malformed and failed operations.

This work depends on interface discovery, consumer access, localized resources, templates, reports and observable legacy execution. Tests must cover boundary values, null and empty collections, stale requests, retries, failed saves and external failures. Coverage will demonstrate tested paths only, not semantic or fleet-wide completeness. Unknown consumers and behaviour available only in production remain unresolved risks.

CHG-003 Introduce an Incremental Modular Deployment Model

The application evidences separable notification, movement, party, route, classification, finance, guarantee, document, reporting and audit concerns, but it does not establish a need for independently deployed microservices. The decision is to change internal structure incrementally while preserving domain asymmetry and external contracts. The initial target is a modular deployable with explicit boundaries, compatibility adapters and prohibited cross-boundary writes, rather than an assumed service-per-domain design.

Azure App Service is the preferred initial hosting candidate if the recovered runtime is supported. Azure Container Apps remains an alternative for container-dependent or independently scaled workers. Azure Functions may host bounded asynchronous tasks. Azure Kubernetes Service is deferred unless operational or workload requirements justify its complexity. Final selection depends on baseline recovery, scaling evidence, networking, supplier support and operating-system dependencies.

CHG-004 Formalize Notification and Assessment Lifecycles

Notifications and assessments are distinct, and import, export and transit behaviour is asymmetric. Observed states include unsubmitted, submitted, notification received, awaiting payment, in assessment, ready to transmit, transmitted, decision required, consented, withdrawn, objected, reassessed, prohibited, closed, unlocked and resubmitted. The decision is to preserve observed state meanings while resolving the contradiction between submitted and awaiting payment before implementing a target state machine.

The target is an explicit transition contract identifying actor, preconditions, editability, authorization, persistence, audit, event and failure semantics for each transition. Enum order will not define lifecycle order. This depends on business, policy, finance and reporting owners and on characterization of current callers. Terminal states, withdrawal, resubmission, unlocking, prohibition, archive and closure semantics remain uncertain.

CHG-005 Separate Movement, Shipment, Receipt and Outcome Rules

Movements, shipments, receipts, rejection, recovery and completion are evidenced as distinct concepts. Internal and external receipt and completion paths have different identifiers, file and date requirements. The decision is to preserve those differences and resolve outcome precedence before consolidation. The target is a movement boundary with explicit commencement, submission, receipt, partial rejection, rejection, recovery, completion and cancellation commands.

Acceptance must cover ordering, duplicate and stale submissions, quantity effects, future and backdated dates, bulk-operation failure, and whether partially rejected movements can complete. The work depends on the lifecycle contract, quantity rules, file handling and authorization policy. Receipt versus rejection authority, overwrite behaviour, whitespace-only reasons, multiple outcome records, cancellation versus deletion and transaction scope remain unresolved.

CHG-006 Define Identifier Allocation and Lookup Contracts

Notification numbers may be authority-specific and normalized before lookup, while movement numbers may use the smallest unused positive value. The decision is to preserve visible formats and lookup behaviour until uniqueness and error contracts are confirmed, while changing unsafe allocation to use database-level concurrency protection if the existing rule is retained.

The target includes explicit normalization, formatting, uniqueness scope, malformed and unmatched result behaviour, shipment-number bounds and deterministic allocation under concurrency. This depends on data profiling, database-provider capabilities and caller characterization. Existing database constraints, locking behaviour, sequence rules and authority boundaries are unknown.

CHG-007 Centralize Authoritative Party and Relationship Checks

The system represents organisations, users, memberships, owners, producers, exporters, importers, carriers, facilities, treatment sites, authorities and customs offices inconsistently. The decision is to change mutation handling so posted or hidden relationship values never establish ownership or authorization. Existing business relationships and historical meanings are preserved pending cardinality decisions.

The target is an authoritative party and location boundary whose current records are reloaded for every mutation and checked against identity, organisation, authority, role and lifecycle state. This depends on identity discovery, data profiling and an accepted relationship model. Ownership scope, tenant boundaries, membership lifecycle, address relationships, facility cardinality and the requirement for exactly one treatment site remain unresolved.

CHG-008 Implement Centrally Testable Authorization Policies

Actors include external owners, shared users, assessors, authorities, administrators, read-only users, service clients and unauthenticated callers, but declarations and user-interface controls do not prove enforcement. The decision is to change authorization to centrally testable action-resource policies while preserving confirmed access outcomes until reviewed.

The target policy evaluates authenticated identity, organisation, authority, ownership, membership, resource and lifecycle state. High-impact actions such as reassignment, ownership transfer, deletion, guarantee decisions, finance changes, archive and user administration require explicit policy and audit review. State-changing retrieval operations should move to protected non-GET commands after characterization and consumer transition. This depends on a complete action-resource matrix and identity tracing. Default-allow behaviour, anonymous reachability, dual-control needs and current enforcement remain uncertain.

CHG-009 Resolve Identity, Authentication and Secret Management

Bearer and cookie authentication, token refresh, claims transformation, identity precedence, inactive-user handling, client credentials, password reset and email verification are incomplete. The decision is to resolve these contracts before identity migration and urgently investigate any environment-wide auto-confirmation or unsafe temporary-state deserialization.

Microsoft Entra ID is the candidate for workforce and service identities. External customer identity is deferred pending population and lifecycle discovery. Managed Identities and Azure Key Vault are proposed for supported service access and secrets, keys and certificates. This change depends on preserving user-to-business relationships and inventorying all clients and scopes. Token storage, malformed-claim behaviour, external identity platform choice and account migration remain undecided.

CHG-010 Establish Authoritative Date and Calendar Semantics

Evidence contains contradictory thirty-day, sixty-day, working-day, consent-period and movement-window rules. The decision is to preserve workflow-specific observed results and resolve each rule rather than normalize by assumption. The target distinguishes date-only business values from timezone-aware processing instants and uses a clock abstraction and named authority-specific calendar service.

Acceptance must specify inclusivity, start-date treatment, timezone, holiday source, precedence and whether each rule warns or blocks. It must cover malformed values, report ranges, migration dates, receipt and recovery ordering, and payment and refund dates. Business and policy ownership, authoritative calendars and several stated limits remain uncertain.

CHG-011 Define Quantity, Unit and Rounding Contracts

Tonnes, kilograms, litres and cubic metres are evidenced, with inconsistent treatment of zero, negative, null and incomplete values. The decision is to preserve stored meanings and visible results until conversion, compatibility and precision rules are approved. Heuristic conversion will not be treated as authoritative.

The target is explicit unit typing, decimal precision, conversion factors, operation order, tolerance, overflow handling and rounding ownership. Acceptance must address consent limits, remaining authorization, active loads, shipment counts and rejection effects where applicable. This depends on domain decisions and data profiling. Mixed-unit compatibility and whether existing calculations are defects or contractual behaviour remain unresolved.

CHG-012 Isolate Finance, Pricing, Payments and Refunds

Payments may be cumulative and distinguish credits, debits, cleared amounts, balances and refunds. Pricing appears authority-specific and effective-dated. The decision is to preserve current financial records and outputs while resolving currency, precision, tax, rounding, overlapping-price precedence, missing prices and records containing both credit and debit.

The target is a finance boundary using explicit decimal and rounding rules, effective-dated pricing versions, auditability and deterministic replay from business inputs rather than display values. Refund validation must define zero and negative amounts, earliest-payment and future-date rules, and result semantics. This depends on legal, policy, finance and downstream invoice owners. Conflicting calculator evidence prevents a current equivalence claim.

CHG-013 Resolve Guarantee Cardinality and Decision Semantics

Guarantees support application, completion, approval, refusal, release and supersession, but evidence conflicts over whether one or multiple approved guarantees are permitted. The decision is to preserve history and defer new uniqueness constraints until cardinality, matching-reference behaviour, self-approval and release-versus-supersession rules are resolved.

The target is an explicit guarantee lifecycle with eligibility, cover, date, reference, active-load, decision-history, transaction and event contracts. Acceptance must include concurrent approvals, failed decisions and supersession. This depends on data profiling for multiple approved records and accountable business approval. Commented-out limits are not accepted requirements.

CHG-014 Preserve Route, Waste and Reference-Data Meaning

Routes, customs points, transit ordering, transport methods, waste classifications, recovery and disposal operations, packaging and sentinel values have workflow-specific meanings. The decision is to preserve historical codes, obsolete values, “not listed” and “not applicable” distinctions while resolving route multiplicity, resequencing, customs requirements and completeness rules.

The target is a route and classification boundary with ordered transit data and versioned reference meanings. It must not silently deduplicate, normalize or reclassify historical records. This depends on reference-data ownership and profiling of duplicates, ordinals and obsolete codes. Facility rules, European-route behaviour, concentration limits and model-specific treatment of zero or negative values remain uncertain.

CHG-015 Secure Uploads, Downloads and Generated Documents

The application supports uploads, downloads, templates, annexes and generated documents whose filenames, layouts, ordering and visible content are compatibility-sensitive. The decision is to preserve those outputs while changing binary storage and scanning controls after characterization.

Azure Blob Storage with private containers is the preferred target, with relational metadata remaining authoritative for ownership and authorization. Uploads should enter quarantine and be promoted only after size, content, signature and malware checks. Unknown, timeout and error outcomes require an agreed fail-safe contract. This depends on a selected scanner, retention policy and document comparison tests. Rescanning, cleanup, legal hold, reproducibility and document-conversion support remain undecided.

CHG-016 Introduce Durable Integration Delivery

Current database changes, events, email, files, caches and external effects may commit independently. The decision is to change integration delivery to a durable pattern without making existing synchronous interfaces asynchronous where callers require immediate results.

Azure Service Bus is the preferred candidate for durable commands and integration events, combined with a transactional outbox, duplicate-tolerant consumers, dead-letter handling and reconciliation. Event Grid is deferred to lightweight notifications that do not require durable ordered business processing. This depends on confirmed ordering, retry, replay and failure contracts. Current dispatch timing, idempotency, dead-letter ownership and coordination with commits remain unknown.

CHG-017 Separate Reporting Read Models Without Changing Outputs

Reports use queries, views, procedures, raw SQL and denormalized caches, with differing import and export logic. The decision is to preserve columns, aliases, workbook structure, ordering, status derivation, null handling and date boundaries until automated comparison and consumer acceptance support change.

The target is controlled read models or replicas where confirmed freshness permits, with explicit authorization, refresh and reconciliation. Reporting replacement depends on baseline outputs, large-result characterization and ownership of freshness requirements. Cache invalidation, unit conversion, outcome derivation, performance and downstream consumers remain uncertain.

CHG-018 Strengthen Transaction, Concurrency and Audit Boundaries

Persistence combines ORM access, repositories, SQL, procedures, direct saves, files, audits, caches and events. The decision is to change representative mutations to explicit transactional seams, concurrency handling and distinguishable attempted, denied, failed and successful audit outcomes.

The target uses relational transactions for atomic business changes, concurrency tokens where stale updates are possible, and outbox records for integration intent. Security audit, business history and diagnostic telemetry remain separate. This depends on tracing each mutation and confirming database capabilities. Universal rollback, retry, compensation and current audit timing are not established.

CHG-019 Profile and Migrate Data Deterministically

Migrations affect statuses, authorities, routes, classifications, facilities, guarantees, finance, receipts, users, reports and caches, with risks of deletion, truncation, multiplication and ambiguous backfills. The decision is to defer destructive transformation until profiling and contract decisions are accepted.

Azure SQL Database is the leading target candidate if compatibility is demonstrated; Azure SQL Managed Instance remains a coexistence option for material instance-scoped or incompatible SQL dependencies. Cosmos DB is not proposed for relational records. Each migration slice requires preflight diagnostics, retained rejects, deterministic survivor rules, source-to-target counts, referential checks, semantically valid totals, checkpoints, rerun behaviour and rollback or forward recovery. Applied migration state, provider dependencies and rollback feasibility remain uncertain.

CHG-020 Establish Azure Observability and SRE Operations

Operational visibility, service levels, support ownership and recovery performance are not established. The decision is to introduce telemetry and recovery practices before claiming reliability benefits. Azure Monitor, Application Insights and Log Analytics are candidates for correlated metrics, traces, logs, dependency telemetry and alerts.

The target includes correlation from HTTP request through command, database commit, outbox, message handling and external calls, plus tested runbooks for deployment failure, dependency outage, stuck queues, scanner failure, orphaned files, event failure, report divergence and migration interruption. Availability, performance, retention, support hours, recovery-time and recovery-point objectives remain decisions, not assumed targets. Backups require scheduled restore tests.

CHG-021 Deliver Through Reversible, Independently Verifiable Slices

The decision is to change through coexistence rather than a single replacement. The first slice should establish inventory, executable baseline, deployment, telemetry and one end-to-end characterization path without changing business behaviour. Later slices should resolve lifecycle and security contracts, strengthen server-side policy, introduce durable integrations and file controls, and replace bounded capabilities behind compatibility interfaces.

Every slice requires acceptance tests, reconciliation, controlled activation, and rollback or forward recovery. Feature flags may separate deployment from activation, but flags affecting authorization or data meaning require audit and removal plans. The critical path currently passes through baseline recovery, contract resolution, identity and authorization discovery, data profiling and external dependency access. Change freezes, business calendars, downtime, environments, production-like data, licences and supplier lead times remain dependencies.

CHG-022 Establish Measures, Scenarios and Approval Gates

The objectives include lower change risk and lead time, better security, reliability, recoverability, supportability and visibility, but no baseline or target is supplied. The decision is to defer benefit claims and delivery estimates until measurement is established. Candidate indicators include deployment frequency, change lead time, failed-change rate, restoration time, availability, unresolved security findings, unsupported dependencies, restore success, dead-letter age, reconciliation differences, authorization-test coverage and incident rate.

Each measure requires an approved baseline, target, owner, data source, sampling period and calculation method. Low, central and high delivery scenarios must be produced after the first accepted slice from measured human effort, automated-agent runtime, supplier waiting time and elapsed calendar time. Architecture approval also depends on runtime and topology confirmation, domain and authorization contracts, data profiles, interface inventory, service-level decisions, threat model, residency and retention decisions, Azure option validation, operational ownership, cost assessment and demonstrated migration and recovery procedures.