TASK22211: version memory-bank and backfill change-log stream

.gitignore

@@ -58,10 +58,5 @@ CONTRIBUTING_AI.md
 GUARDRAILS.md
 ai-prompts/
 context/
-memory-bank/
 workflows/
 AI_CONTEXT.md
-memory-bank/activeContext.md
-memory-bank/change-log.md
-memory-bank/refactor-plan-actions-index.md
-memory-bank/progress.md

memory-bank/## 1) Prioritized debt list.md

@@ -0,0 +1,54 @@
+## 1) Prioritized debt list
+
+1. Monolithic `actions/index.js` (over-coupled “god module”)
+2. Inconsistent API error handling/response contracts across `pages/api/**`
+3. Sensitive/verbose logging in app + API paths
+4. Endpoint sprawl and duplicated proxy patterns (`pages/api/endpoint/*_api.js`)
+5. i18n routing complexity in large rewrite maps
+6. Sparse automated test coverage for high-risk flows
+7. Legacy/stale commented patterns in critical files
+
+## 2) Impact of each item
+
+- **1) `actions/index.js` monolith**
+    - High blast radius for any change; weak modularity and hard ownership boundaries.
+    - Evidence: ~100+ exports mixing search, auth, account, file, PDF, notify, CRM concerns.
+
+- **2) API contract inconsistency**
+    - Clients must handle errors inconsistently; reliability and observability suffer.
+    - Evidence: many handlers return raw `res.status(400).json(error)` while others shape custom outputs.
+
+- **3) Verbose/sensitive logging**
+    - Privacy/security risk plus noisy telemetry.
+    - Evidence: 300+ `console.log` occurrences, including auth/email/upload-related contexts.
+
+- **4) Endpoint duplication**
+    - Maintenance cost and drift risk (validation/auth/error semantics diverge over time).
+    - Evidence: repeated patterns across many `_api.js` proxy handlers.
+
+- **5) i18n rewrite complexity**
+    - Higher risk of EN/CY divergence as routes evolve.
+    - Evidence: large manual rewrite map + separate i18n page namespace config.
+
+- **6) Sparse tests**
+    - Release confidence depends heavily on manual checks; slower, riskier change cadence.
+
+- **7) Stale patterns**
+    - Increased cognitive load and unclear source-of-truth behavior in some modules.
+
+## 3) Recommended next cleanup targets
+
+1. **Decompose `actions/index.js` by domain** (structure-only first, keep barrel exports).
+2. **Add shared API handler utilities** for validation/error envelope; migrate top sensitive endpoints first.
+3. **Implement logging redaction wrapper + policy** and remove direct logs in auth/email/file paths.
+4. **Create high-risk smoke tests** (auth callback, search endpoint, upload negative-path, email failure-path).
+5. **Extract proxy/integration helpers** (token/hash/header/retry) to reduce endpoint duplication.
+6. **Add EN/CY parity CI checks** for route and locale key consistency.
+
+## 4) Runtime note (updated)
+
+- `server.js` and `server/server.js` exist in the repository but are **not the active production concern** for the current refactor stream.
+- Current baseline runtime for this debt plan is the standard Next runtime path (`npm start`).
+- Runtime canonicalization is therefore removed from the active prioritized debt list unless deployment evidence changes.
+
+If you want, I can convert this into a sprint-ready debt register (ID, owner, effort, risk reduction, target milestone).

memory-bank/Absolutely — here’s a senior architectur.md

@@ -0,0 +1,94 @@
+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.

memory-bank/README.md

@@ -0,0 +1,38 @@
+# Memory Bank Operating Protocol
+
+## Purpose
+
+Capture durable engineering knowledge for PEDW FrontEnd so AI agents and humans make consistent, safe decisions over time.
+
+## When to Update
+
+Update memory-bank entries when any of the following occur:
+
+1. A non-trivial architectural or implementation decision is made.
+2. A recurring pattern is introduced or standardized.
+3. A pitfall/incident/root cause is discovered.
+4. A release introduces meaningful behavior/risk changes.
+5. Open questions block safe delivery.
+
+## Who Updates
+
+- **AI agent:** must add or amend entries for non-trivial changes completed during a task.
+- **Human engineer/reviewer:** validates or amends entries during PR review.
+- **Tech lead/owner:** resolves open questions and marks decisions as accepted/superseded.
+
+## Required Metadata (for every new entry)
+
+- `date:` YYYY-MM-DD
+- `author:` agent name or person
+- `scope:` files/routes/features affected
+- `type:` decision | pattern | pitfall | change | question | glossary
+- `rationale:` why this matters
+- `impact:` user/system/security/i18n/a11y implications
+- `status:` proposed | accepted | superseded | open | resolved
+
+## Entry Quality Rules
+
+- Keep entries concise and specific to this repository.
+- Link to concrete files/paths where possible.
+- Do not include secrets, tokens, personal data, or sensitive payload examples.
+- If uncertain, record assumptions explicitly and add to `open-questions.md`.

memory-bank/change-log.md

@@ -0,0 +1,131 @@
+# Change Log (AI/Human Curated)
+
+## Entry Template
+
+```
+date: YYYY-MM-DD
+author: <agent|name>
+scope: <files/routes/features>
+type: change
+rationale: <why change was made>
+impact: <user/system/security/i18n/a11y>
+status: completed|rolled-back|partial
+
+Summary:
+Validation:
+Follow-ups:
+```
+
+---
+
+### CL-001: TASK22211 endpoint search-document contract consistency slice
+
+date: 2026-03-23  
+author: Cline  
+scope: `pages/api/endpoint/{getsearchdocumenthistory_api,getsearchdocumenthistorypaged_api,getsearchdocumentdetails_api,getsearchdocumentdetailspaged_api,getsearchdocumentTypes_api}.js`, `tests/phase21/endpoint-handler-contract.test.cjs`  
+type: change  
+rationale: Continue the endpoint contract-consistency stream by normalizing a coherent search-document handler cluster that still used raw error passthrough and noisy legacy logging patterns.  
+impact: Improved negative-path consistency and safer error contract handling in search-document endpoints while preserving success payload behavior.  
+status: completed
+
+Summary:
+
+- Branch created from `SIPS-Development`: `TASK22211-endpoint-search-document-contract-consistency`.
+- Standardized five search-document handlers to `respondError`/`respondSuccess` usage.
+- Added explicit required-input guards:
+    - `DOCUMENT_ID_REQUIRED` for history/historypaged
+    - `INCIDENT_ID_REQUIRED` for details/detailspaged/types
+    - `ORDER_BY_REQUIRED`, `FIELD_SORT_REQUIRED`, `SHOW_NUMBER_OF_RECORDS_REQUIRED` for details-paged query requirements
+- Removed noisy direct logging in paged/details code paths.
+- Preserved success contract patterns (pass-through or transformed payloads where already established).
+- Expanded phase21 endpoint tests with missing-input, catch-path, and success parity assertions for this cluster.
+
+Validation:
+
+- `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/exhaustive-deps` warnings; no new lint errors)
+
+Follow-ups:
+
+- Continue the next endpoint cluster using the same pattern (bounded slice + phase21 test expansion).
+- Keep response success payloads contract-stable and avoid broad relay/auth refactors in this stream.
+
+### CL-002: TASK22211 endpoint token handler contract consistency slice
+
+date: 2026-03-23  
+author: Cline  
+scope: `pages/api/endpoint/getToken.js`, `tests/phase21/endpoint-handler-contract.test.cjs`  
+type: change  
+rationale: Close out remaining non-standard endpoint contract handling by normalizing the legacy token endpoint to shared API response helpers and explicit error coding.  
+impact: Improved endpoint error consistency and test coverage for token acquisition failures while preserving successful token payload passthrough.  
+status: completed
+
+Summary:
+
+- Refactored `getToken.js` to use `respondSuccess` and `respondError` from `pages/api/middleware/apiResponse`.
+- Removed legacy raw `res.status(...).json(...)`/bare status assignment pattern and dead logging artifacts.
+- Added explicit catch-path contract: `TOKEN_FETCH_FAILED` with 400 status.
+- Added endpoint phase21 tests for:
+    - success token payload passthrough
+    - catch-path error contract assertion
+
+Validation:
+
+- `node tests/phase21/api-contract-slice1.test.cjs` -> pass
+    - helper: 4/4
+    - file-handler: 11/11
+    - email-handler: 12/12
+    - endpoint-handler: 147/147
+- `npm run lint` -> warnings only (pre-existing `react-hooks/exhaustive-deps` warnings; no new lint errors)
+
+Follow-ups:
+
+- Remaining outlier API handler for this consistency stream is `pages/api/file/generateappealpdfcopy.js` (not yet on shared response helpers).
+
+### CL-003: TASK22211 endpoint contract-hardening stream backfill (all known slices)
+
+date: 2026-03-23  
+author: Cline  
+scope: `pages/api/endpoint/*_api.js`, `pages/api/endpoint/getToken.js`, `tests/phase21/endpoint-handler-contract.test.cjs`  
+type: change  
+rationale: Backfill memory-bank traceability so the complete known TASK22211 contract-consistency stream is documented in one place now that memory-bank is being versioned.  
+impact: Improves governance/auditability of API contract hardening, makes rollout and rollback analysis easier, and records exactly which endpoint clusters were normalized.  
+status: completed
+
+Summary:
+
+- Backfilled all known TASK22211 slices currently on branch (in commit order):
+    - `b57f3de` search-document endpoint contracts + phase21 coverage
+    - `9af541a` my-portal retrieval endpoint contracts
+    - `b880364` basic search endpoint contracts
+    - `a106dea` DNS basic search endpoint contracts
+    - `b5a3a62` portal module + LPA case endpoint contracts
+    - `4601d7c` case detail endpoint contracts
+    - `2959c7d` delete/watched-case endpoint contracts
+    - `b59f13a` metadata + linked-case endpoint contracts
+    - `bcf03a6` form + publication endpoint contracts
+    - `e0e91c8` DNS + representation endpoint contracts
+    - `98e159d` case creation + media endpoint contracts
+    - `88e4586` advanced-search-paged endpoint contract
+    - `cb69bbe` case update + CRM task endpoint contracts
+    - `722ef98` hash + metadata endpoint contracts
+    - `134f99c` address-search endpoint contract
+    - `8b6ed73` new-appeal appeal-types endpoint contract
+    - `eec59e8` token endpoint contract handling
+- Across the stream, handlers were standardized toward `respondSuccess`/`respondError`, required-input guards, and explicit negative-path error codes while preserving success payload compatibility.
+- Phase21 endpoint contract suite was expanded incrementally alongside each slice.
+
+Validation:
+
+- Stream validation baseline (latest known run):
+    - `node tests/phase21/api-contract-slice1.test.cjs` -> pass (endpoint-handler 147/147)
+    - `npm run lint` -> warnings only (pre-existing `react-hooks/exhaustive-deps`; no new lint errors)
+
+Follow-ups:
+
+- Continue with remaining non-standard API outlier(s), notably `pages/api/file/generateappealpdfcopy.js`.
+- Keep future slices logged in this file at commit-time now that memory-bank is versioned.

memory-bank/decisions.md

@@ -0,0 +1,47 @@
+# Decisions (ADR-Lite)
+
+## Entry Template
+
+```
+date: YYYY-MM-DD
+author: <agent|name>
+scope: <files/routes/features>
+type: decision
+rationale: <why>
+impact: <user/system/security/i18n/a11y>
+status: proposed|accepted|superseded
+
+Decision:
+Consequences:
+Related:
+```
+
+---
+
+### D-001: AI Governance Bundle Structure
+
+date: 2026-03-11  
+author: Cline  
+scope: .clinerules, ai-prompts/, context/, memory-bank/  
+type: decision  
+rationale: Establish a durable AI collaboration system aligned to repository risks and delivery model.  
+impact: Improves consistency, review quality, and safety for auth/i18n/public-service flows.  
+status: accepted
+
+Decision:
+Adopt four artifact pillars:
+
+1. `.clinerules` for operating constraints,
+2. `ai-prompts/` for reusable task templates,
+3. `context/` for architecture/domain references,
+4. `memory-bank/` for persistent project knowledge.
+
+Consequences:
+
+- AI/human contributors use a shared protocol.
+- Non-trivial changes require memory-bank updates.
+
+Related:
+
+- `context/project-overview.md`
+- `memory-bank/README.md`

memory-bank/glossary.md

@@ -0,0 +1,79 @@
+# Glossary
+
+## Entry Template
+
+```
+date: YYYY-MM-DD
+author: <agent|name>
+scope: <domain/component>
+type: glossary
+rationale: <why term clarity matters>
+impact: <delivery/quality implication>
+status: active
+
+Term:
+Definition:
+Where used:
+```
+
+---
+
+### G-001: DNS
+
+date: 2026-03-11  
+author: Cline  
+scope: domain flows  
+type: glossary  
+rationale: Distinguishes DNS journey from general case search flows.  
+impact: Reduces implementation ambiguity in routing and UI behavior.  
+status: active
+
+Term:
+DNS
+
+Definition:
+Developments of National Significance journey and related case/search routes.
+
+Where used:
+
+- `pages/dns/**`, `pages/myportal/dns/**`, DNS-related search/detail pages
+
+### G-002: HYDRATE
+
+date: 2026-03-11  
+author: Cline  
+scope: Redux store lifecycle  
+type: glossary  
+rationale: Critical to SSR/client state consistency.  
+impact: Prevents store regressions during refactors.  
+status: active
+
+Term:
+HYDRATE
+
+Definition:
+`next-redux-wrapper` action used to merge server-side state into client-side store.
+
+Where used:
+
+- `store/store.js`
+
+### G-003: Locale Parity
+
+date: 2026-03-11  
+author: Cline  
+scope: i18n and routing  
+type: glossary  
+rationale: Core quality expectation for bilingual public service.  
+impact: Ensures consistent EN/CY experience.  
+status: active
+
+Term:
+Locale parity
+
+Definition:
+Equivalent behavior/content correctness across English (`en`) and Welsh (`cy`) for affected user journeys.
+
+Where used:
+
+- `locales/**`, `i18n.js`, `next.config.js`, user-facing pages/components

memory-bank/open-questions.md

@@ -0,0 +1,57 @@
+# Open Questions
+
+## Entry Template
+
+```
+date: YYYY-MM-DD
+author: <agent|name>
+scope: <files/routes/features>
+type: question
+rationale: <why unresolved>
+impact: <user/system/security/i18n/a11y>
+status: open|resolved
+
+Question:
+Needed from:
+Decision deadline:
+```
+
+---
+
+### Q-001: Auth Logging Redaction Standard
+
+date: 2026-03-11  
+author: Cline  
+scope: auth/email APIs and actions logging  
+type: question  
+rationale: Existing logging appears verbose in sensitive flows.  
+impact: Potential privacy/security exposure via operational logs.  
+status: open
+
+Question:
+What mandatory redaction and logging policy should be enforced for auth/email/document flows?
+
+Needed from:
+Security lead + application owner
+
+Decision deadline:
+Before next auth/notification release
+
+### Q-002: Test Strategy Baseline for Sparse `tests/`
+
+date: 2026-03-11  
+author: Cline  
+scope: testing strategy repository-wide  
+type: question  
+rationale: `tests/` currently appears minimal; validation relies heavily on manual checks.  
+impact: Increased regression risk and slower release confidence.  
+status: open
+
+Question:
+What minimum automated coverage should be required per change type (feature, bug fix, high-risk integration)?
+
+Needed from:
+Engineering lead + QA
+
+Decision deadline:
+Before next major feature cycle

memory-bank/patterns.md

@@ -0,0 +1,66 @@
+# Patterns
+
+## Entry Template
+
+```
+date: YYYY-MM-DD
+author: <agent|name>
+scope: <files/routes/features>
+type: pattern
+rationale: <why>
+impact: <user/system/security/i18n/a11y>
+status: accepted|superseded
+
+Pattern:
+When to use:
+Example paths:
+```
+
+---
+
+### P-001: Thin Pages, Reusable Logic Elsewhere
+
+date: 2026-03-11  
+author: Cline  
+scope: `pages/`, `components/`, `lib/`, `actions/`  
+type: pattern  
+rationale: Improve maintainability and reduce route-level complexity.  
+impact: Better testability and safer incremental changes.  
+status: accepted
+
+Pattern:
+Keep route pages focused on composition and orchestration; place reusable behavior in `lib/`, `components/`, or `actions/`.
+
+When to use:
+
+- New features in existing routes
+- Refactors reducing duplication across pages/components
+
+Example paths:
+
+- `pages/newappeal/**`
+- `components/newappeal/**`
+- `actions/index.js`
+
+### P-002: EN/CY Parity for User-Facing Changes
+
+date: 2026-03-11  
+author: Cline  
+scope: `locales/`, `i18n.js`, `next.config.js`, user-facing pages  
+type: pattern  
+rationale: Service requires bilingual consistency and reliable route behavior.  
+impact: Prevents locale divergence and citizen confusion.  
+status: accepted
+
+Pattern:
+Any user-facing change should include EN and CY text/route validation as part of done checks.
+
+When to use:
+
+- New/changed labels, messages, headings
+- New/changed route aliases or rewrites
+
+Example paths:
+
+- `locales/en/**`, `locales/cy/**`
+- `next.config.js`, `i18n.js`

memory-bank/pitfalls.md

@@ -0,0 +1,62 @@
+# Pitfalls
+
+## Entry Template
+
+```
+date: YYYY-MM-DD
+author: <agent|name>
+scope: <files/routes/features>
+type: pitfall
+rationale: <why recorded>
+impact: <user/system/security/i18n/a11y>
+status: open|mitigated|resolved
+
+Pitfall:
+How to detect:
+How to avoid:
+```
+
+---
+
+### PF-001: Locale Rewrite Drift
+
+date: 2026-03-11  
+author: Cline  
+scope: `next.config.js`, `i18n.js`, user-facing routes  
+type: pitfall  
+rationale: Route/content parity can silently break across EN/CY if only one side is updated.  
+impact: Broken navigation and inconsistent bilingual experience.  
+status: mitigated
+
+Pitfall:
+Adding or modifying a route in one locale without corresponding rewrite/translation updates.
+
+How to detect:
+
+- Manual navigation check for EN and CY aliases.
+- Verify page namespace mappings in `i18n.js`.
+
+How to avoid:
+
+- Treat route + translation + rewrite as one change unit.
+
+### PF-002: Sensitive Logging in Auth/Notification Paths
+
+date: 2026-03-11  
+author: Cline  
+scope: `pages/api/auth/[...nextauth].js`, `pages/api/email/**`, `actions/index.js`  
+type: pitfall  
+rationale: Debug logs in these paths can expose identifiers or callback tokens.  
+impact: Security and privacy risk.  
+status: open
+
+Pitfall:
+Verbose console logs around auth URLs, email payloads, or user identifiers.
+
+How to detect:
+
+- Search changed files for `console.log` and inspect payload content.
+
+How to avoid:
+
+- Use redacted logging and avoid printing callback tokens/user-sensitive data.

memory-bank/productContext.md

@@ -0,0 +1,37 @@
+# Product Context — PEDW FrontEnd
+
+## Primary user workflows
+
+1. **Public discovery**
+    - Search planning cases (basic, advanced, address, DNS).
+    - Open case summary pages and review documents/history.
+
+2. Authenticated portal (`/myportal/**`)
+    - Sign in via magic-link email.
+    - View dashboards/worklists (my cases, watched cases, awaiting submission, representations).
+    - Start or continue appeal/representation submission flows.
+
+3. **Role-shaped behavior**
+    - General users can create appeals and representations.
+    - LPA users get authority-scoped views and representation actions; raise-appeal behavior is restricted.
+
+## Core domain concepts
+
+- **Case / Incident**: core planning entity shown in search, detail, and portal journeys.
+- **Appeal type**: controls collection/field behavior and some UI logic.
+- **Representation window**: date-gated period controlling whether representation actions are available.
+- **Watched case / email notifications**: user subscriptions to case changes.
+- **DNS**: Developments of National Significance-specific journey and pages.
+
+## Business logic patterns visible in code
+
+- Case summary UI varies by appeal type and case attributes.
+- Representation actions are conditionally shown by appeal type, role, and date windows.
+- Locale-sensitive behavior affects links, routes, labels, and email template choice.
+- New-case-reference notifications include preferred-language checks before template selection.
+
+## Important user-facing behaviors
+
+- Welsh route aliases are mapped in `next.config.js` and must remain in sync with page behavior.
+- Breadcrumb/back-navigation behavior is actively maintained across search -> case -> portal routes.
+- Document visibility/download flows are central to case transparency and must remain stable.

memory-bank/projectbrief.md

@@ -0,0 +1,25 @@
+# Project Brief — PEDW FrontEnd
+
+## What this project is
+
+PEDW FrontEnd is a bilingual (English/Welsh) public-service web portal for Planning and Environment Decisions Wales. It supports public case discovery and authenticated portal workflows for planning appeals, representations, and DNS (Developments of National Significance) journeys.
+
+## Problem it solves
+
+- Gives citizens and stakeholders a single place to search planning cases and view case details/documents.
+- Enables authenticated users to create/manage appeals and representations through structured online workflows.
+- Provides role-aware dashboard experiences (e.g. general portal users and LPA users) without exposing internal CRM complexity.
+
+## Key users / use cases
+
+- **Public users:** search, filter, and view planning case information and documents.
+- **Authenticated portal users:** manage account details, submit/continue appeals, submit representations, track watched and submitted items.
+- **LPA users:** authority-scoped dashboard and representation-related actions.
+- **Admin/support users:** review new appeals/documents and operational lists via admin endpoints/UI.
+
+## High-level success criteria
+
+1. Core public and portal journeys remain reliable (search, case detail, my portal, new appeal, representation).
+2. Security-sensitive flows (auth/session, API relay/hash, file/document handling) remain intact.
+3. EN/CY parity is maintained for routes and user-facing content.
+4. Accessibility baseline remains acceptable for keyboard navigation, headings, labels, and focus behavior.

memory-bank/refactor-backlog.md

@@ -0,0 +1,51 @@
+# Refactor Backlog (Maintainability + System Integrity)
+
+Last updated: 2026-03-12
+
+## Priority 1 — Split `actions/index.js` by concern
+
+- **Problem:** Single high-coupling module mixes API clients, hash/token helpers, logging, file/email/domain operations.
+- **Why it matters:** Hard to reason about changes; high regression risk from unrelated edits.
+- **Target outcome:** Small modules with explicit boundaries (e.g. `relayClient`, `fileClient`, `notifyClient`, `caseService`, `authService`).
+- **Initial scope:** create façade layer first, then migrate call sites incrementally.
+- **Detailed plan:** `memory-bank/refactor-plan-actions-index.md`
+- **Test gate:** add unit regression tests + coverage reporting as part of this refactor.
+
+## Priority 2 — Centralize relay/hash/token forwarding logic
+
+- **Problem:** `pages/api/endpoint/**` and related routes duplicate request-signing + token + forwarding behavior.
+- **Why it matters:** Security-sensitive drift and inconsistent error handling.
+- **Target outcome:** Shared relay utility enforcing one signing contract, one timeout/retry policy, one error map, one redacted logging strategy.
+- **Initial scope:** pilot on a small endpoint group, then roll out pattern.
+
+## Priority 3 — Extract breadcrumb/back-link route-state rules
+
+- **Problem:** Navigation logic in `components/breadcrumbs.js` and case summary is branch-heavy and query-dependent.
+- **Why it matters:** Frequent regressions in search -> case -> myportal paths.
+- **Target outcome:** Pure route-state helpers with table-driven tests; UI component mainly renders output.
+- **Initial scope:** isolate `va/adv/ads/key` decision matrix first.
+
+## Priority 4 — Standardize security guards in `pages/api/file/**`
+
+- **Problem:** Hash/guard enforcement appears inconsistent across file endpoints.
+- **Why it matters:** Uneven protection for document upload/download/delete paths.
+- **Target outcome:** Shared guard middleware for hash/auth/input validation + consistent negative-path responses.
+- **Initial scope:** enforce a common pre-handler contract on high-risk routes first.
+
+## Priority 5 — Establish minimum automated regression baseline
+
+- **Problem:** Limited automated tests for high-risk logic.
+- **Why it matters:** Repeated regressions and heavy manual verification burden.
+- **Target outcome:** Focused test suite for pure logic and high-risk decisions.
+- **Initial scope:**
+    1. breadcrumb decision matrix
+    2. representation eligibility/date windows
+    3. hash utility behavior
+    4. locale rewrite mapping sanity checks
+
+## Sequencing recommendation
+
+1. Priorities 2 + 4 (security/integrity foundation)
+2. Priority 3 (high-change regression hotspot)
+3. Priority 1 (structural maintainability)
+4. Priority 5 (continuous safety net, starts early and expands)

memory-bank/systemPatterns.md

@@ -0,0 +1,41 @@
+# System Patterns — PEDW FrontEnd
+
+## Architecture style
+
+- Next.js 14 (Pages Router) monolith with route handlers in `pages/` and API handlers in `pages/api/**`.
+- Mix of SSR/client rendering with Redux hydration (`HYDRATE`) and client persistence.
+- Integration-heavy backend-for-frontend pattern: many internal API routes proxy to external services.
+
+## Module boundaries
+
+- `pages/`: route composition and API endpoints.
+- `components/`: UI feature modules (case, search, dns, myportal, account, admin, mapping).
+- `actions/`: shared API client helpers, token/header/hash helpers, and side-effect utilities.
+- `lib/`: domain/form helper logic.
+- `store/`: Redux reducers, wrapper, and persistence config.
+- `prisma/`: auth/session persistence schema.
+
+## API patterns
+
+- Endpoint naming commonly uses `*_api.js` under `pages/api/endpoint/`, `pages/api/file/`, `pages/api/admin/`.
+- Recurring endpoint implementation pattern:
+    1. build query path,
+    2. create HMAC hash (`hash` query param),
+    3. fetch OAuth token,
+    4. forward to relay URL,
+    5. return normalized JSON / error.
+- Swagger annotations are embedded in many API files for route documentation.
+
+## Data and integration boundaries
+
+- **Auth/session persistence**: Prisma models (`User`, `Account`, `Session`, `VerificationToken`) on SQL Server.
+- **Case/business data**: fetched via API proxy routes to Dynamics/relay endpoints (not via Prisma business models).
+- **File/document handling**: Azure blob-backed APIs under `pages/api/file/**`, including hash checks on sensitive routes.
+
+## Internal conventions and recurring implementation choices
+
+- Bilingual route mapping through `next.config.js` rewrites plus `i18n.js` page namespace mapping.
+- Security headers are split across `middleware.js` (CSP + runtime security headers) and `next.config.js` static headers.
+- Breadcrumb/back-link logic is centralized in `components/breadcrumbs.js` and depends on route/query state.
+- Case summary behavior is appeal-type driven with branching UI/eligibility logic in `components/case/summary.js`.
+- Proxy and direct variants coexist for some APIs (`*proxy_api.js`), so behavior parity must be checked when changing one side.

memory-bank/techContext.md

@@ -0,0 +1,43 @@
+# Tech Context — PEDW FrontEnd
+
+## Languages and framework
+
+- JavaScript-first codebase (TypeScript tooling present).
+- Next.js `^14.2.28` with Pages Router.
+- React `^18.2.0`.
+
+## Core libraries in active use
+
+- Auth: `next-auth` + Prisma adapters.
+- Data/state: `redux`, `react-redux`, `next-redux-wrapper`, `redux-persist`, `redux-thunk`, `redux-form`.
+- Data access/integration: `axios`, `crypto-js`, `jsonpath-plus`.
+- i18n: `next-translate`, locale config in `i18n.js`.
+- Storage/infrastructure integrations: `@azure/storage-blob`, `@azure/storage-queue`, `@azure/identity`.
+- Notifications/telemetry: `notifications-node-client` (GOV.UK Notify), `applicationinsights`.
+- PDF/maps: `@react-pdf/renderer`, `react-pdf`, `leaflet`, `react-leaflet`, `google-map-react`.
+
+## Runtime and configuration
+
+- Standard app start script uses Next runtime (`npm start`).
+- Additional custom server entries exist (`server.js`, `server/server.js`) but are currently treated as non-active for the refactor baseline unless deployment evidence indicates otherwise.
+- Environment-driven config for auth, relay/API roots, hash key, notify key, and database URL.
+
+## Tooling and quality gates
+
+- Linting: `npm run lint` (`next lint`).
+- Formatting conventions from `.prettierrc`: 4 spaces, no trailing commas.
+- Prisma client generation script available: `npm run prisma:generate`.
+
+## CI/CD and deployment artifacts
+
+- `azure-pipelines.yml` exists (legacy-looking Node 10 build pipeline).
+- `Jenkinsfile` exists (Node 20 + Docker build/push/deploy flow).
+- `Dockerfile` exists (Node 20 Alpine runtime).
+- Repository contains mixed deployment artifacts; active production path should be treated as environment-dependent unless confirmed.
+
+## Local development workflow
+
+- `npm install`
+- `npm run dev`
+- `npm run lint`
+- `npm run build && npm start` for production-like verification