Source-derived document; review findings and open questions with the application owner.

Interfaces

Interfaces

The supplied evidence describes several interface surfaces rather than one confirmed endpoint inventory. These include server-rendered ASP.NET MVC/Razor pages, Web API operations, mediator-style request and response contracts, repository and service interfaces, database procedures, document and file interfaces, email and scanning interfaces, reporting outputs, and client-side AJAX interactions. The relationship between these surfaces, their deployment boundaries, and their complete route configuration is not established.

Web and MVC interfaces

The MVC application exposes area- and route-based workflows for notification creation and editing, import and export notifications, movements and shipments, assessments, financial guarantees, facilities, producers, carriers, customs offices, waste codes, transit states, address-book records, comments, account management, reporting, uploads, ownership changes, sharing, cancellation, deletion, and archive operations.

Observed route patterns include area-specific routes containing notification or entity identifiers, including routes resembling:

• Notification-Application/{id}/{controller}/{action}/{entityId}
• Import-Notification/{id}/{controller}/{action}/{entityId}
• Notification-Movements/{notificationId}/{controller}/{action}
• Export-Movement/{Id}/{controller}/{action}/{entityId}
• Address-Book/{controller}/{action}/{id}
• Admin/{controller}/{action}/{id}

Other evidence describes lower-case, dashed route helpers and different administrative route registrations. It is unresolved whether these route patterns coexist, which parameters are mandatory, whether redirects depend on ambient route values, and which actions are publicly reachable.

MVC actions commonly accept form-bound view models, hidden identifiers, selected values, dates, quantities, files, notification numbers, status values, and TempData or session state. Invalid model state generally returns the current view with errors in the observed controller patterns, although some invalid paths reload a fresh model or call another action, potentially losing posted values or lookup collections. Several actions redirect without explicitly carrying a notification identifier; route defaults, ambient values, session state, or custom helpers may preserve context, but this is not demonstrated.

Views render anti-forgery tokens on several forms, including selected upload, deletion, date, comments, sharing, customs-office, and workflow forms. Token rendering establishes request-construction support only. The evidence does not establish server-side validation coverage for every state-changing action.

Web API and technical endpoints

A separate Web API surface is described as using OWIN, Web API routing, Autofac, bearer-token validation, IdentityServer middleware, claims transformation, and JSON serialization. Startup reportedly enables attribute and conventional routing and dispatches requests through Web API. The complete endpoint inventory, route activation, identity authority, token format, claims model, and production composition are unknown.

The virus-scanning area exposes an authenticated POST scan operation and an anonymous GET health-style operation using the same route family. The GET is reported to return "ok"; this is source-level evidence and does not prove deployed availability or intended public exposure. The POST accepts uploaded bytes and invokes an IVirusScanner abstraction. Selected exceptions are mapped to HTTP 401, 403, or 500 responses, but other exception paths, detailed error disclosure, request limits, scanner timeouts, temporary-file handling, cleanup, and quarantine behaviour are unresolved.

An API mediator can obtain either a user token or a client-credentials token and forward requests to an IWS client. Requests marked as allowing unauthorised users may bypass an explicit unauthenticated-user rejection. It is unknown whether downstream operations distinguish user and client-credentials tokens, whether client credentials grant access to protected resources, or whether every request passes through this mediator.

Mediator request and response interfaces

The request layer contains typed mediator contracts, commonly implementing IRequest<T>, with handlers implementing asynchronous request-handler interfaces in the supplied source. Requests cover:

• notification creation, submission, resubmission, completion, withdrawal, consent, prohibition, archive references and key dates;
• assessment decisions, status changes, comments and consultations;
• movement creation, receipt, rejection, partial rejection, completion, cancellation, deletion and audit;
• shipment counts, quantities, dates, units, packaging and carriers;
• exporters, importers, producers, facilities and address-book records;
• state of export, state of import, transit states, routes, customs offices and entry or exit points;
• waste types, waste codes, operations, physical characteristics and chemical composition;
• financial guarantees, payments, refunds and additional charges;
• user administration, sharing, ownership changes and account operations;
• reports, searches, notification progress, document generation and file retrieval.

Response types include bool, Guid, nullable identifiers, Unit, strings, arrays, collections, validation summaries, status values, byte arrays, file data and structured DTOs. A Boolean or identifier result does not have a uniform demonstrated meaning: it may represent success, existence, eligibility, a created identifier, or another application-specific outcome. Some request classes have private setters and constructor-populated values, while others expose public setters or mutable collections. The active model binder, serializer and validation pipeline are not supplied.

Identifier naming is inconsistent across the contracts, including Id, NotificationId, ImportNotificationId, MovementId and notification-number fields. Some contracts contain apparent spelling variants such as NotificaitonId, SetAcknowlegedDate, PartailReject and PreconstedAnswer. These names may be compatibility-sensitive or may be defects; their effect on registration, serialization, binding and callers is unknown.

Inputs and validation boundaries

Inputs may originate from browser forms, AJAX requests, uploaded files, API clients, database rows, session or TempData, and internal mediator calls. Visible inputs include notification and movement identifiers, notification numbers, user identifiers, emails, competent authorities, countries, dates, quantities, units, statuses, decision values, comments, codes, selected collections, files and file metadata.

Some local rules are visible or test-derived, including:

• required notification and movement identifiers in selected requests;
• required and ordered dates, future-date restrictions and consent-period checks;
• positive shipment counts and quantities;
• shipment-number and comment length limits;
• payment, refund, refusal-reason and financial-guarantee checks;
• operation-code compatibility and uniqueness;
• waste-code type and not-applicable constraints;
• facility and treatment-site cardinality assumptions;
• transit-state country, authority, point and ordinal checks;
• uploaded-file presence and selected MIME-type checks;
• notification ownership, competent-authority and shared-user checks in selected paths.

Resource strings and browser attributes demonstrate displayed requirements but do not prove server-side enforcement. There are unresolved contradictions in the prenotification-to-shipment limit, variously described as 30 or 60 days, and in some date, quantity and customs-office rules. Hidden fields, posted identifiers, status values, charges and selected records are client-modifiable; the evidence does not consistently show that handlers reload authoritative state, verify membership and ownership, or reconcile submitted values.

Files, documents and reporting interfaces

File interfaces support document upload, movement certificates, signed prenotifications, receipt and recovery files, annex files, bulk uploads, document downloads, and generated DOCX, PDF, CSV and XLSX outputs. File content may be passed as byte arrays or uploaded-file objects. A scanning abstraction reports outcomes such as unknown, clean, virus and error, but the complete scanner implementation, limits, timeouts, quarantine, retention, cleanup and failure policy are unknown.

Document generation uses OpenXML-oriented blocks and factories. Blocks merge data into templates and may create annexes. Main-document and annex block ordering is significant, and several paths use strict First() or Single() assumptions for fields, rows, facilities or treatment sites. Missing or duplicated template data can therefore fail. Template loading, rendering, persistence, transmission, access control, retry and recovery are not established.

Report interfaces accept date ranges, competent authorities, notification types, trade direction, organisations, parties, statuses, operation codes, text fields, operators and selected output columns. Report outputs include spreadsheet results with report-specific filenames and selected worksheets or columns. Some reports use cached or denormalised data and are described as being one day behind live data. The refresh trigger, completeness, date-boundary semantics, query failures and output protection are unknown. One report path uses inclusive SQL BETWEEN ranges, while another uses a start-inclusive/end-exclusive range, so adjacent-period behaviour is not uniform in the visible evidence.

Email, OAuth and external-service interfaces

Email interfaces construct HTML and plain-text messages from templates and send them through an asynchronous sender. Approval and rejection handlers use event data, configured templates and links. The sender’s Boolean result is not always inspected, and SMTP configuration, pickup-directory processing, transport security, retry behaviour, delivery confirmation and failure recovery are not established.

OAuth and OpenID Connect clients support resource-owner, client-credentials, refresh-token and user-information requests. Reported scopes include openid, api1, api2, api3, all_claims, profile and offline_access. The evidence does not establish token storage, expiry enforcement, refresh rotation, issuer validation, TLS configuration, secret management or downstream claim requirements.

The Companies House client accepts a company reference, obtains a token, calls a configured endpoint, applies a retry wrapper in the observed path, and maps invalid references or exceptions into result objects. URL construction, response validation, timeout, retry and cancellation behaviour, logging and external-service availability are not fully evidenced.

Persistence and database interfaces

Repositories expose retrieval, creation, update, deletion, archive, audit, search, reporting and movement operations. They use Entity Framework-style queries, LINQ, raw SQL and stored procedures. Some operations use explicit transactions; others perform multiple saves or separate file and database operations without a visible common transaction. Stored-procedure contracts, result-set schemas, transaction scope, isolation, rollback, concurrency handling and exception propagation are generally unknown.

Database procedures support notification search, reporting, archiving, deletion, movement processing, progress retrieval and cache refresh. Some procedures visibly use transactions and re-raise errors, while others have less evident rollback or error handling. Import and export movement procedures differ in how conflicting outcome flags are treated: one rejects multiple flags, while another processes the first matching branch. This is a source-visible inconsistency whose intended policy is unresolved.

Failure paths and interface limits

Observed or plausible failure paths include invalid model state, missing or duplicated records, strict Single or First lookups, malformed dates or identifiers, invalid enum values, null collections, failed external calls, invalid or oversized files, scanner errors, missing templates, malformed merge fields, failed database operations, stale TempData, missing session state, authorization failures, anti-forgery failures, maintenance mode and HTTP error responses.

Some handlers return null, an empty object, false or true for missing or failed conditions; other paths throw domain, argument, format, security or null-reference exceptions. One authorization-related call broadly catches Exception and returns null, while an archive path reportedly returns false after rollback. These behaviours are repository- or handler-specific and cannot be generalized.

The evidence does not establish a uniform error schema, HTTP response contract, logging policy, retry policy, user-facing failure mapping, or compensation for partial work. It also does not establish whether files, audit records, events, email, database writes and external calls are atomic. The complete interface inventory, caller relationships, deployment activation and runtime enforcement remain unresolved.

Content quality review

Advisory; not approval. Review status: advisory.

Overall assessment

The draft is broadly relevant to an interfaces.md purpose and is appropriately cautious about source-level evidence, deployment uncertainty, and unresolved behaviour. It captures the major interface families represented in the evidence: MVC/Razor, Web API, mediator contracts, persistence, files, documents, reporting, email, scanning, OAuth, and external services.

However, it is much closer to a broad system-risk narrative than an interface document. It contains substantial duplication of the supplied system overviews and review backlog, while omitting a compact, directly usable inventory of interface names, consumers, inputs, outputs, protocols, authorization declarations, and failure contracts. Its length also makes it difficult to distinguish confirmed interface facts from inferred or merely possible behaviours.

Relevance and structure

The main interface categories are relevant, but the document should more clearly distinguish:

• externally reachable HTTP interfaces;
• browser-rendered forms and AJAX endpoints;
• internal mediator request/response contracts;
• repository and service interfaces;
• database procedures and reporting objects;
• file, document, email, scanning, OAuth, and external-service interfaces.

At present, the opening list says the evidence describes “several interface surfaces,” but later sections present large collections of business capabilities without consistently identifying the actual interface boundary. For example, lists of notification, movement, waste, and financial-guarantee operations describe domain scope, but do not say whether each operation is an MVC action, mediator request, repository method, stored procedure, or merely a represented model capability.

A more useful structure would use a repeated pattern for each interface family:

1. interface or route name;
2. evidence status;
3. caller or consumer;
4. inputs;
5. outputs;
6. authorization or CSRF metadata;
7. validation;
8. failure behaviour;
9. unresolved questions.

The current draft should also be shortened or cross-referenced to a separate domain/workflow document. Much of the lifecycle, financial-guarantee, movement, migration, and security material is relevant background but not necessary in this level of detail for an interface inventory.

Unsupported or over-broad claims

The draft generally uses qualifying language, but several formulations still risk implying more support than the evidence provides.

“ The MVC application exposes area- and route-based workflows” should be narrowed to something such as: “The supplied source contains MVC areas, controllers, views, and route registrations or route patterns for the following workflows.” The evidence does not establish that every listed workflow is deployed, reachable, or part of one application.

Likewise, the sentence that “the MVC application exposes” workflows for notification creation, reporting, uploads, sharing, deletion, and archive operations aggregates evidence from views, controllers, requests, tests, and summaries. Presence of a view or request does not establish an exposed or functioning endpoint. The draft should label each item as a view, controller action, request contract, test expectation, or inferred capability.

The phrase “MVC actions commonly accept form-bound view models, hidden identifiers, selected values, dates, quantities, files, notification numbers, status values, and TempData or session state” is directionally supported, but “commonly” is not demonstrated quantitatively. “Observed actions accept” would be more precise.

The “Failure paths and interface limits” section explicitly includes “observed or plausible failure paths.” Plausible paths are not evidence of interface behaviour. They should be separated into:

• directly observed failure handling;
• test-derived failure handling;
• static risk or verification candidate;
• unknown behaviour.

Similarly, “File interfaces support…” combines actual upload views, request types, document-generation code, and inferred capabilities. It should say which operations are directly evidenced and which are only represented by contracts or filenames.

The statement that “the API mediator can obtain either a user token or a client-credentials token and forward requests to an IWS client” is supported by the supplied material, but the following sentence—“whether every request passes through this mediator”—should be brought closer to the claim because it materially limits the scope of the preceding description.

The draft says that “the sender’s Boolean result is not always inspected.” This is supported in some email handlers, but it should not imply a system-wide property. Use “selected approval and rejection handlers await or receive the sender result without a visible decision based on it.”

The statement that report data “is described as being one day behind live data” is evidence from displayed/reporting descriptions, not proof that all reports are delayed. It should be limited to the named reports or cache paths.

Contradictions and ambiguity

The draft does a good job preserving the major contradictions rather than resolving them. In particular, it correctly retains:

• the 30-day versus 60-day prenotification rule;
• conflicting evidence over whether rejection or partial rejection clears receipt data;
• different external and internal completion checks;
• differing import and export stored-procedure handling of conflicting outcome flags;
• inclusive BETWEEN versus start-inclusive/end-exclusive report ranges;
• uncertainty over concrete NotificationReceived versus parent Submitted state.

These should be consolidated into a short “material interface contradictions” section, rather than repeated across several sections. Each entry should identify the competing behaviour, the affected boundary, and the evidence needed to resolve it.

Some apparent contradictions are really differences between interfaces or contexts. For example, internal versus external receipt requirements, report date semantics, and different authorization checks may be deliberate policy differences rather than implementation inconsistencies. The draft generally acknowledges this, but should explicitly distinguish:

• contradiction within the same operation;
• difference between separate operations;
• difference between presentation and backend evidence;
• unresolved provenance or source-range discrepancy.

The draft could also mention that several evidence notes disagree on whether the scanner health GET is confirmed runtime behaviour or only a candidate scenario. It partially handles this by calling it source-level evidence, but the provenance conflict should be made explicit rather than relying on one interpretation.

Missing interface behaviours

For an interfaces document, the largest omission is a systematic inventory of protocol-level properties. The draft mentions many gaps, but does not present them in a way that lets a reader determine what is known for each interface.

The following behaviours are missing or insufficiently organized:

• exact HTTP verbs per action;
• exact route templates and route constraints;
• required versus optional route parameters;
• content types and accepted serialization formats;
• response status codes beyond selected exception mappings;
• response body schemas and error schemas;
• redirects and whether identifiers are preserved;
• pagination parameters, defaults, limits, ordering, and out-of-range handling;
• file download content types, filenames, content-disposition behaviour, and authorization;
• upload size, row, type, content, and timeout limits;
• idempotency and duplicate-request behaviour;
• cancellation and timeout semantics;
• concurrency and stale-update handling;
• retry behaviour and whether retries apply to non-idempotent operations;
• API versioning or compatibility expectations;
• request correlation, audit identifiers, and trace propagation;
• rate limiting or abuse controls;
• cache headers, cache invalidation, and freshness guarantees;
• transaction boundaries across database, files, events, and email;
• treatment of partial success in bulk, archive, copy, and multi-record operations.

Some of these are mentioned later as unknowns, but they should be part of the interface assessment rather than dispersed through the narrative.

The mediator section also lacks a clear contract table or equivalent prose inventory. It lists response types, but does not associate them with request categories or explain the known meaning of each result. The draft correctly warns that bool, Guid, and Unit lack uniform meaning; it should go further and identify representative examples where the meaning is known, such as a created identifier, a success result, or a no-op result.

The database section describes repository and procedure families but does not distinguish read, write, deletion, archive, reporting, and cache-refresh operations consistently. It should identify where SQL procedures are directly observed versus merely named in requests or repositories.

Evidence gaps

The draft accurately identifies most major evidence gaps:

• incomplete route registrations;
• missing controller, handler, repository, validator, and middleware implementations;
• absent dependency-injection and deployment composition;
• missing stored-procedure bodies and result schemas;
• no test execution results;
• no deployed endpoint inventory;
• no production configuration or runtime traces;
• no complete database schema or representative production data;
• no evidence of operational monitoring, backups, retention, or recovery.

A further important gap is provenance. The supplied evidence consists largely of consolidated notes and second-opinion summaries, with conflicting source ranges, hashes, omitted-file reports, and some analyses that explicitly lacked reliable citations or failed during review. The draft mentions this generally, but should state that many individual claims cannot be traced to a uniquely identified source artifact from the material provided. That is an evidence limitation, not a defect in the application.

The absence of a complete endpoint inventory is also not itself evidence that endpoints are missing. The draft usually observes this distinction, but phrases such as “the complete interface inventory … remains unresolved” should be retained consistently whenever it discusses absent routes, callers, or registrations.

Specific corrections recommended

Replace broad capability statements with evidence-qualified interface statements. For example:

> “The supplied material contains MVC controllers and Razor views for selected notification, movement, assessment, upload, sharing, reporting, and administrative workflows. It does not establish that each represented workflow has an active production route.”

Replace “the MVC application exposes” with “the supplied source describes” unless a route registration and action are directly evidenced.

Separate the route examples into exact registrations and approximate patterns. A route “resembling” Notification-Application/{id}/{controller}/{action}/{entityId} should not be presented alongside an exact route unless the distinction is explicit.

Separate browser-visible validation from server-side validation throughout. The draft does this in places, but the long validation list could still be read as an inventory of enforced rules. Label items as “displayed,” “model-level,” “test-derived,” “domain-level,” “database-level,” or “enforcement unknown.”

Replace “plausible failure paths” with “verification candidates” and identify whether each is source-visible, test-derived, or inferred.

Reduce repeated statements about deployment, authorization, transactionality, and evidence limitations. One concise limitations section, plus local qualifications where needed, would be clearer and less repetitive.

Add a compact interface summary near the beginning. In prose, it should state that the evidence supports interface families but not a definitive endpoint inventory, and then enumerate the known route families, API operation families, mediator contracts, persistence interfaces, file/document services, reporting paths, and external clients.

Clarify that selected MIME-type validation is validation of the posted MIME value or declared content type unless file-signature or content inspection is directly evidenced. It should not be read as proof that the file’s actual type was verified.

Clarify that an anonymous health-style GET returning "ok" is a source-level implementation observation, not proof of public deployment, health semantics, or acceptable exposure.

For OAuth scopes, state that the evidence shows configured or reported scope values, but does not establish whether scopes are conjunctive, alternative, enforced by the authority, or required by each downstream operation.

For reports, identify the named cached or denormalized paths rather than implying that all reports are stale.

Unresolved questions to add

The review should leave the following questions explicit:

• Which MVC routes and Web API routes are registered in the deployed application, and which projects provide them?
• Which route patterns are exact registrations versus helper-generated or inferred examples?
• What is the definitive HTTP method, request schema, response schema, and authorization requirement for each state-changing action?
• Are ambient route values intentionally relied upon, and are route values revalidated against the current notification?
• What is the authoritative validation layer for each major operation: binder, controller, FluentValidation, domain object, handler, repository, or database?
• Are hidden identifiers, statuses, charges, dates, selected records, and user IDs always reconstructed or checked against persisted state?
• Which Boolean, GUID, nullable, and Unit results mean success, existence, eligibility, or created identity?
• Are external and internal movement paths intentionally different, and must their validation and authorization be equivalent?
• Are files, database records, audits, events, and email coordinated transactionally or through compensation/outbox mechanisms?
• What are the upload limits, scanner failure policy, quarantine policy, cleanup policy, and retention period?
• Which report date-boundary convention is authoritative for each report?
• Are the anonymous health and smoke-test operations intentionally public in the deployed environment?
• What is the authoritative identity, claims, role, and scope model for the MVC and API surfaces?
• Which source snapshot and deployment version do the conflicting route, migration, and interface observations describe?

Overall, the draft is a useful cautious synthesis, but it should be revised toward a smaller, explicitly classified interface inventory. The principal issue is not that it identifies too few concerns; it is that it contains too many broad system observations without consistently showing the exact interface boundary or the strength and provenance of the supporting evidence.