pedwfrontend/context/architecture.md

Architecture Reference

Runtime Topology

1. Next.js runtime serves UI routes and API routes (legacy custom server files are present but not active).
2. Next.js pages/ router handles UI routes and API routes under pages/api/**.
3. Middleware (middleware.js) injects CSP nonce and security headers on requests/responses.
4. State management initialized in pages/_app.js with Redux wrapper and persistence.
5. Authentication handled by next-auth in pages/api/auth/[...nextauth].js with Prisma adapter.

Key Architectural Modules

• Presentation layer: pages/, components/, styles/
• State layer: store/store.js + slice reducers
• Domain/service helpers: actions/, lib/
• Auth persistence: Prisma client + prisma/schema.prisma (next-auth tables in SQL Server)
• Portal business data access: API routes query Dynamics 365 CRM through Azure Service Bus Relay using REST + OData patterns
• Relay integrity check: forwarded CRM-bound API requests include a path-based hash, validated by relay with shared key before forwarding
• Infrastructure glue: middleware.js, next.config.js, i18n.js (plus legacy server files not in active runtime)

High-Risk/Guarded Paths

1. pages/api/auth/[...nextauth].js
   • Email sign-in flow, callback/redirect logic, session setup.
2. middleware.js and security headers in next.config.js
   • CSP and browser hardening policies.
3. store/store.js
   • HYDRATE, persistence, logout storage clearing.
4. prisma/schema.prisma
   • Source of truth for auth/account persistence tables.
5. File and notification APIs in pages/api/file/**, pages/api/email/**
   • Upload/document/email side effects and sensitive data handling.

i18n and Routing Model

• Locales: en, cy (configured in i18n.js).
• Locale detection disabled; domain and route rewrites drive behavior.
• Welsh route aliases maintained in next.config.js rewrites.
• Any new user-facing route should consider:
  • translation resources in locales/en and locales/cy
  • rewrite parity where a Welsh alias is expected
  • auth pages and callback URLs for locale correctness

External Integration Touchpoints

• Dynamics 365 CRM (portal business data): reached via frontend API routes that send REST/OData queries through Azure Service Bus Relay.

• Azure Service Bus Relay request integrity: relay endpoint is configured via API_ROOT; request path (excluding domain) is hashed client-side and validated relay-side with shared hash key.

• Azure Storage/Queue: actions/azurestorage.js, selected API handlers.

• GOV.UK Notify email: actions/index.js, pages/api/email/**, next-auth email provider.

• Application Insights: components/azureappinsights.js and related environment configuration.

• Mapping embeds and map libs: components/mapping/**, DNS/search components.

• PDF generation/rendering: pages/api/file/generate*.js, components/pdftemplates/**.

Current Endpoint Contract Hardening Status (2026-03)

Recent bounded slices in the endpoint contract-consistency stream have standardized selected high-traffic handlers from raw relay error passthrough to structured response contracts (respondSuccess / respondError) with explicit required-input guards and phase21 contract coverage.

Completed clusters include:

• Search document retrieval cluster (getsearchdocumenthistory*, getsearchdocumentdetails*, getsearchdocumentTypes_api)
• My portal retrieval cluster (getmycases_api, getmyrepresentations_api, getwatchedcases_api, getawaitingsubmission_api)
• Basic search family cluster (getbasicsearchdetails_api, getbasicsearchdetailspaged_api, getbasicsearchpaged_api, getbasicsearch_by_lparref_api)

Guardrail note: success payload contracts are intentionally preserved to avoid frontend regressions, while negative-path behavior is being normalized endpoint-by-endpoint with corresponding phase21 tests.

Legacy / Inactive Components

The following files exist in the repository but are not part of the current active runtime model:

• server.js
• server/server.js

Guidance:

• Do not treat these files as active runtime architecture unless explicitly reactivated.
• If reactivation is proposed, document rationale and rollout/rollback in memory-bank/change-log.md and context/runbook.md.