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

## Current State Assessment and Prioritised Next Steps (2026-03-25)

### Assessment summary

The platform has moved into a stronger operational and architectural posture through sustained bounded refactor slices and contract hardening.

Strengths:

1. **Governance maturity is high**
    - Guardrails are explicit for auth/session integrity, CSP/security headers, Prisma source-of-truth, relay hash integrity, and EN/CY parity.
2. **API reliability posture has improved materially**
    - Endpoint contract hardening and phase21 contract test expansion have reduced inconsistency in negative-path handling.
3. **Relay operations are significantly more robust**
    - Shared relay forwarding now includes bounded retry/timeout policy, structured redacted lifecycle logging, and documented rollout/rollback controls.
4. **Façade decomposition is delivering low-risk progress**
    - `actions` layer migration to shared clients (`relayClient`, `endpointClient`) is reducing duplicated request boilerplate and lowering drift risk.

Primary residual risks/gaps:

1. **Remaining direct-service inconsistency**
    - Some direct services still contain legacy axios/request patterns and bespoke signed-request blocks.
2. **Coverage concentration**
    - Contract tests are strong in targeted slices, but end-to-end/high-value journey coverage in sensitive flows remains comparatively sparse.
3. **Logging hygiene variance**
    - Structured redaction exists in relay paths, but broader codebase logging still has uneven consistency.
4. **i18n parity assurance remains process-heavy**
    - EN/CY parity relies heavily on manual discipline rather than automated parity checks.

### Prioritised next steps

1. **Complete direct-service consistency sweep (low risk, high maintainability)**
    - Prioritise `actions/services/searchDirectService.js` for `getJson`/`requestJson` adoption in bounded slices.
    - Preserve existing error-return behavior contracts per function.
2. **Consolidate signed-request patterns (medium risk, high security clarity)**
    - Introduce a focused signed-request helper for hash-based/signed delete/get pathways currently repeated in service modules.
    - Keep existing hash/header semantics unchanged while reducing duplication.
3. **Add high-value regression automation (high value)**
    - Add focused automated checks for:
        - auth callback/redirect safety
        - one signed-delete negative path
        - one upload/document authorization negative path
        - one EN/CY route parity check
4. **Perform targeted logging hardening in sensitive paths**
    - Continue replacing direct/verbose logging in `auth`, `file`, `email`, and account-sensitive endpoint paths with redacted structured logging patterns.
5. **Introduce EN/CY parity CI checks**
    - Add automated checks for route rewrite parity and locale key alignment to reduce drift and manual burden.
6. **Continue endpoint sprawl reduction**
    - Keep collapsing duplicated proxy/request patterns behind shared helpers in bounded route clusters while preserving public response contracts.

### Recommended execution sequence

- **Sequence A (immediate):** Step 1 + Step 3 (fastest risk reduction per effort)
- **Sequence B (next):** Step 2 + Step 4 (security/logging consistency consolidation)
- **Sequence C (after):** Step 5 + Step 6 (institutionalise parity and reduce long-tail maintenance cost)