robbond/pedwfrontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a3b848cfc10e7775b32002a3def06675ad14730f
pedwfrontend/context/architecture.md
T

9.5 KiB
Raw Blame History

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.

Current State Assessment and Prioritised Next Steps (2026-03-25)

Assessment summary

The platform has moved into a stronger operational and architectural posture through sustained bounded refactor slices and contract hardening.

Strengths:

  1. Governance maturity is high
    • Guardrails are explicit for auth/session integrity, CSP/security headers, Prisma source-of-truth, relay hash integrity, and EN/CY parity.
  2. API reliability posture has improved materially
    • Endpoint contract hardening and phase21 contract test expansion have reduced inconsistency in negative-path handling.
  3. Relay operations are significantly more robust
    • Shared relay forwarding now includes bounded retry/timeout policy, structured redacted lifecycle logging, and documented rollout/rollback controls.
  4. Façade decomposition is delivering low-risk progress
    • actions layer migration to shared clients (relayClient, endpointClient) is reducing duplicated request boilerplate and lowering drift risk.

Primary residual risks/gaps:

  1. Remaining direct-service inconsistency
    • Some direct services still contain legacy axios/request patterns and bespoke signed-request blocks.
  2. Coverage concentration
    • Contract tests are strong in targeted slices, but end-to-end/high-value journey coverage in sensitive flows remains comparatively sparse.
  3. Logging hygiene variance
    • Structured redaction exists in relay paths, but broader codebase logging still has uneven consistency.
  4. i18n parity assurance remains process-heavy
    • EN/CY parity now has targeted automated coverage, but still relies on manual discipline for broader journey-level assurance and CI enforcement.

Prioritised next steps

  1. Complete direct-service consistency sweep (low risk, high maintainability)
    • Prioritise actions/services/searchDirectService.js for getJson/requestJson adoption in bounded slices.
    • Preserve existing error-return behavior contracts per function.
  2. Consolidate signed-request patterns (medium risk, high security clarity)
    • Introduce a focused signed-request helper for hash-based/signed delete/get pathways currently repeated in service modules.
    • Keep existing hash/header semantics unchanged while reducing duplication.
  3. Broaden high-value regression automation (high value)
    • Initial focused checks are now in place for:
      • auth callback/redirect safety
      • signed-delete negative path
      • upload/document authorization negative path
      • EN/CY route parity
    • Next, expand breadth/depth (more journey-level assertions and CI integration).
  4. Perform targeted logging hardening in sensitive paths
    • Continue replacing direct/verbose logging in auth, file, email, and account-sensitive endpoint paths with redacted structured logging patterns.
  5. Introduce EN/CY parity CI checks
    • Add automated checks for route rewrite parity and locale key alignment to reduce drift and manual burden.
  6. Continue endpoint sprawl reduction
    • Keep collapsing duplicated proxy/request patterns behind shared helpers in bounded route clusters while preserving public response contracts.

Recommended execution sequence

  • Sequence A (immediate): Step 1 + Step 3 (fastest risk reduction per effort)
  • Sequence B (next): Step 2 + Step 4 (security/logging consistency consolidation)
  • Sequence C (after): Step 5 + Step 6 (institutionalise parity and reduce long-tail maintenance cost)

Status update (2026-03-25)

  • Sequence A targeted intent is now covered on this branch:
    • Step 1: direct-service consistency sweep completed for this bundle stream
    • Step 3: focused checks added for auth redirect safety and EN/CY rewrite parity, alongside existing signed-delete and upload/document negative-path coverage
  • Remaining work is primarily Sequence B and Sequence C scope.

Cross-check update vs debt list and architect review (2026-03-25)

This architecture status has been cross-checked against:

  • memory-bank/debt-list.md
  • memory-bank/architect-review.md

Current progress snapshot:

  1. Actions monolith decomposition -> in progress with strong momentum
    • shared clients/helpers introduced (relayClient, endpointClient, fileClient, fileRouteBuilder) and adopted across key service modules
    • residual monolith risk remains until broader domain split is complete
  2. API contract consistency -> materially improved
    • large endpoint hardening footprint already delivered, with remaining long-tail cleanup still open
  3. Sensitive logging hardening -> partial
    • relay path improvements exist, but wider auth/email/file logging standardization remains open
  4. Endpoint sprawl reduction -> materially improved
    • repeated relay/proxy patterns reduced through helper reuse
  5. i18n parity assurance -> initial automation in place
    • targeted EN/CY rewrite parity checks now exist; CI-level institutionalization still recommended
  6. High-risk regression automation -> materially improved
    • focused auth redirect safety + signed-delete + upload/document negative-path + EN/CY parity checks now covered
  7. Runtime canonicalization -> still open
    • server entrypoint ambiguity (server.js vs server/server.js) remains an explicit follow-on architecture decision.
Reference in New Issue View Git Blame Copy Permalink