# 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)**.