docs(governance): track context docs and add relay rollout controls

2026-03-24 12:26:32 +00:00
parent 2ac2f51fc3
commit ad0d2bf285
11 changed files with 847 additions and 1 deletions
@@ -0,0 +1,77 @@
+# 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`.