117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
# 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)**.
|