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,116 @@
+# Integration Map
+
+## Overview
+
+This map identifies external or boundary integrations, where they are used, and what to validate when touched.
+
+## 1) Authentication + Account Persistence
+
+- **Tech:** `next-auth`, Prisma adapter, SQL Server via Prisma
+- **Primary files:**
+    - `pages/api/auth/[...nextauth].js`
+    - `prisma/schema.prisma`
+- **Data sensitivity:** High (session/account identity)
+- **Validation focus:**
+    - Sign-in, verify-request, error, and callback behavior
+    - Safe redirect handling
+    - Session expiry and cookie behavior
+
+## 1a) Portal Data Access (CRM via Relay)
+
+- **System of record:** Microsoft Dynamics 365 CRM (portal business/case data)
+- **Query style:** REST API calls and OData query patterns
+- **Transport path:** Frontend API routes -> Azure Service Bus Relay -> Dynamics 365 CRM
+- **Relay endpoint config:** `API_ROOT` environment variable
+- **Request integrity:** Request path (excluding domain) is hashed before forwarding; relay recomputes using shared hash key and validates match
+- **Primary files:**
+    - `pages/api/endpoint/*_api.js`
+    - `actions/index.js` (query construction/helpers, hash generation)
+- **Data sensitivity:** High (case and user-associated business data)
+- **Validation focus:**
+    - Query correctness and filter safety
+    - Relay failure/timeout handling
+    - Hash validation compatibility between frontend and relay
+    - API contract consistency between endpoint handlers
+    - No sensitive payload leakage in logs
+
+## 2) GOV.UK Notify (Email)
+
+- **Tech:** `notifications-node-client`
+- **Primary files:**
+    - `actions/index.js`
+    - `pages/api/email/notify.js`
+    - `pages/api/email/getall.js`
+    - next-auth email provider in `pages/api/auth/[...nextauth].js`
+- **Data sensitivity:** Medium-High (contact details + transactional messaging)
+- **Validation focus:**
+    - Correct template selection (EN/CY)
+    - Error handling and retry/fallback behavior
+    - No sensitive data leakage in logs
+
+## 3) Azure Storage + Queues
+
+- **Tech:** `@azure/storage-blob`, `@azure/storage-queue`, managed identity patterns
+- **Primary files:**
+    - `actions/azurestorage.js`
+    - `pages/api/file/**`
+    - selected admin utils under `components/admin/utils/**`
+- **Data sensitivity:** High (documents/uploads)
+- **Validation focus:**
+    - File type/size/path validation
+    - Upload/download/delete authorization boundaries
+    - Queue message integrity and failure handling
+
+## 4) Application Insights
+
+- **Tech:** `applicationinsights`, React app insights integration
+- **Primary files:**
+    - `components/azureappinsights.js`
+- **Data sensitivity:** Medium (telemetry may include operational metadata)
+- **Validation focus:**
+    - Telemetry starts only when configured
+    - No personal/sensitive payloads in custom logs/events
+
+## 5) Mapping
+
+- **Tech:** `leaflet`, `react-leaflet`, `google-map-react`, embedded map URLs
+- **Primary files:**
+    - `components/mapping/**`
+    - `components/search/dnssearchresults.js`
+    - CSP/middleware references to map frame sources
+- **Validation focus:**
+    - CSP/frame-src compatibility
+    - Graceful handling when external map resources are unavailable
+
+## 6) PDF and Document Generation
+
+- **Tech:** `@react-pdf/renderer`, template components, upload APIs
+- **Primary files:**
+    - `pages/api/file/generatepdf.js`
+    - `pages/api/file/generateappealpdf.js`
+    - `components/pdftemplates/**`
+- **Validation focus:**
+    - Correct template selection by appeal/document type
+    - Encoding/formatting robustness for submitted rich text
+    - Safe download headers and document naming
+
+## Integration Change Checklist (apply whenever any integration is modified)
+
+1. Confirm required env vars are documented (without exposing values).
+2. Verify timeout/error/negative path behavior.
+3. Validate EN/CY output where user-facing content is integration-driven.
+4. Record risk and validation evidence in PR and `memory-bank/change-log.md`.
+
+### Relay policy change minimum evidence (operational)
+
+For changes to shared relay timeout/retry/logging policy, include:
+
+1. Non-prod smoke evidence for:
+    - deterministic non-retry classes (`400`, `401`, `403`, `404`)
+    - transient retry classes (`429`, `503`, timeout transport failures)
+2. Structured redacted logging verification and duplicate-log suppression confirmation.
+3. Rollback/migration controls:
+    - quick config mitigation (`RELAY_RETRY_MAX=0`)
+    - full commit revert path.
+
+Reference: `context/runbook.md` -> **Relay Hardening Rollout Playbook (TASK22239)**.