pedwfrontend/memory-bank/architect-review.md

Absolutely — here’s a senior architecture review of this repository.

Update: TASK22211 completed slice (2026-03-23)

• Branch: TASK22211-endpoint-search-document-contract-consistency
• Scope completed:
  • pages/api/endpoint/getsearchdocumenthistory_api.js
  • pages/api/endpoint/getsearchdocumenthistorypaged_api.js
  • pages/api/endpoint/getsearchdocumentdetails_api.js
  • pages/api/endpoint/getsearchdocumentdetailspaged_api.js
  • pages/api/endpoint/getsearchdocumentTypes_api.js
  • tests/phase21/endpoint-handler-contract.test.cjs
  • memory-bank/change-log.md
• Pattern applied:
  • standardized structured error envelopes via respondError
  • preserved existing success contract behavior via respondSuccess
  • added explicit required-input guards for missing document/case/query inputs
  • removed noisy direct console.log usage in touched handlers
• Validation snapshot:
  • node tests/phase21/api-contract-slice1.test.cjs -> pass
    • helper 4/4
    • file-handler 11/11
    • email-handler 12/12
    • endpoint-handler 53/53
  • npm run lint -> warnings only (pre-existing react-hooks warnings)

Suggested next coherent slice

• Endpoint contract consistency follow-on for case/myportal retrieval cluster still using raw error passthrough patterns, applying the same bounded refactor + phase21 test expansion model.

1) Current architecture summary

• Platform shape: Next.js 14 (pages router) + React 18, with a custom Node server and also a legacy Express-style server under server/server.js.
• API layer: Large pages/api/** surface (endpoint/file/email/admin/auth), many routes acting as thin proxies to upstream systems (CRM/relay/Azure).
• State/auth: Redux (next-redux-wrapper + persistence) and next-auth + Prisma adapter for account/session persistence.
• i18n/routing: EN/CY via next-translate, i18n.js, and many Welsh rewrites in next.config.js.
• Integration-heavy domains: Azure storage/queues, GOV.UK Notify, mapping embeds/libs, PDF generation.

2) Strengths

• Clear high-level domain separation by folders (pages, components, store, actions, prisma, locales).
• Strong security intent (CSP + secure headers + auth/session infrastructure in place).
• Bilingual-first routing model is explicit and robustly represented in config.
• Operational integration maturity: telemetry, notifications, document handling, and mapping already embedded.
• Recently added governance docs (.clinerules, GUARDRAILS.md, CONTRIBUTING_AI.md, context/, memory-bank/) materially improve consistency and delivery safety.

3) Risks (scalability, maintainability, coupling, boundaries, operations, debt)

1. God-module risk in actions/index.js (very high maintainability/coupling risk)
   Hundreds of mixed responsibilities (auth helpers, search, uploads, notifications, case operations) create high fan-in/fan-out and regression blast radius.
2. Boundary leakage between UI and integration concerns
   Frontend-facing actions are tightly coupled to relay/API details, hashes, token flow assumptions, and endpoint naming conventions.
3. Inconsistent runtime topology / entrypoint ambiguity
   Both root server.js and server/server.js exist with different runtime behavior, increasing deployment confusion and operational drift risk.
4. Logging/privacy exposure risk
   Multiple debug logs in sensitive paths (auth/email/payloads) risk leaking identifiers or confidential request data.
5. API proliferation with naming inconsistency and limited shared contract enforcement
   Many _api.js endpoints with repeated patterns suggest technical debt and likely drift in validation/error handling semantics.
6. Scalability bottlenecks in synchronous proxy patterns
   High reliance on serial external calls and heavy payload operations (search/doc/PDF flows) without strong evidence of caching, backpressure, or circuit-breaking.
7. Test coverage fragility
   Sparse automated tests means confidence depends heavily on manual checks, slowing safe change velocity and increasing incident probability.
8. i18n rewrite complexity growth
   Large rewrite maps increase cognitive load and chance of EN/CY divergence as route count expands.

4) Prioritized recommendations

1. Decompose actions/index.js into domain modules (highest priority)
   • Split into actions/search, actions/case, actions/account, actions/docs, actions/notify, etc.
   • Add a stable facade export to avoid immediate call-site churn.
2. Establish explicit service boundaries for API integrations
   • Create integration adapters in lib/services/* (CRM/relay/azure/notify).
   • Keep API routes as orchestrators with shared validation/error wrappers.
3. Resolve server runtime canonically
   • Choose one entrypoint for dev/test/prod, deprecate the other, simplify scripts and ops docs.
4. Implement secure logging policy + redaction utility
   • Centralized logger; block raw payload/token/user-data logging by default.
5. Standardize API contract/error envelope
   • Shared response/error shape and input validation helper used by all sensitive endpoints.
6. Introduce incremental architecture tests
   • Start with high-risk auth/file/email negative-path API tests.
7. Tame i18n rewrite sprawl
   • Introduce parity checks (lint/CI) for EN/CY route + locale key synchronization.

5) Low-risk next improvements (next 1–2 sprints)

• Add a single redaction helper and replace highest-risk console.log usage first (auth/email/file flows).
• Add API wrapper utility for consistent try/catch + error response formatting, then migrate 5–10 high-traffic routes.
• Create actions/ module split with barrel exports (no behavioral change, structure-only).
• Add CI guard checks: npm run lint + locale key parity + forbidden logging patterns in sensitive files.
• Decide and document canonical startup path in context/runbook.md and package scripts.
• Add a small smoke test suite for auth sign-in callback, public search endpoint, and one upload negative-path scenario.

If you want, I can turn this into a concrete 30/60/90-day architecture hardening roadmap with owners, sequencing, and expected risk reduction per step.