pedwfrontend/context/integration-map.md

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