# 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`.