From 51eb9b5a4fb75631e8b83efe6a802dec0682a09e Mon Sep 17 00:00:00 2001 From: robbond Date: Mon, 23 Mar 2026 12:32:44 +0000 Subject: [PATCH] TASK22211: version memory-bank and backfill change-log stream --- .gitignore | 5 - memory-bank/## 1) Prioritized debt list.md | 54 ++++++++ ...bsolutely — here’s a senior architectur.md | 94 +++++++++++++ memory-bank/README.md | 38 +++++ memory-bank/change-log.md | 131 ++++++++++++++++++ memory-bank/decisions.md | 47 +++++++ memory-bank/glossary.md | 79 +++++++++++ memory-bank/open-questions.md | 57 ++++++++ memory-bank/patterns.md | 66 +++++++++ memory-bank/pitfalls.md | 62 +++++++++ memory-bank/productContext.md | 37 +++++ memory-bank/projectbrief.md | 25 ++++ memory-bank/refactor-backlog.md | 51 +++++++ memory-bank/systemPatterns.md | 41 ++++++ memory-bank/techContext.md | 43 ++++++ 15 files changed, 825 insertions(+), 5 deletions(-) create mode 100644 memory-bank/## 1) Prioritized debt list.md create mode 100644 memory-bank/Absolutely — here’s a senior architectur.md create mode 100644 memory-bank/README.md create mode 100644 memory-bank/change-log.md create mode 100644 memory-bank/decisions.md create mode 100644 memory-bank/glossary.md create mode 100644 memory-bank/open-questions.md create mode 100644 memory-bank/patterns.md create mode 100644 memory-bank/pitfalls.md create mode 100644 memory-bank/productContext.md create mode 100644 memory-bank/projectbrief.md create mode 100644 memory-bank/refactor-backlog.md create mode 100644 memory-bank/systemPatterns.md create mode 100644 memory-bank/techContext.md diff --git a/.gitignore b/.gitignore index 6c2b14ec..8a8ed18a 100644 --- a/.gitignore +++ b/.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 diff --git a/memory-bank/## 1) Prioritized debt list.md b/memory-bank/## 1) Prioritized debt list.md new file mode 100644 index 00000000..b31fedaf --- /dev/null +++ b/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). diff --git a/memory-bank/Absolutely — here’s a senior architectur.md b/memory-bank/Absolutely — here’s a senior architectur.md new file mode 100644 index 00000000..356cb597 --- /dev/null +++ b/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. diff --git a/memory-bank/README.md b/memory-bank/README.md new file mode 100644 index 00000000..8665899b --- /dev/null +++ b/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`. diff --git a/memory-bank/change-log.md b/memory-bank/change-log.md new file mode 100644 index 00000000..9e63b68c --- /dev/null +++ b/memory-bank/change-log.md @@ -0,0 +1,131 @@ +# Change Log (AI/Human Curated) + +## Entry Template + +``` +date: YYYY-MM-DD +author: +scope: +type: change +rationale: +impact: +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. diff --git a/memory-bank/decisions.md b/memory-bank/decisions.md new file mode 100644 index 00000000..43fcc8de --- /dev/null +++ b/memory-bank/decisions.md @@ -0,0 +1,47 @@ +# Decisions (ADR-Lite) + +## Entry Template + +``` +date: YYYY-MM-DD +author: +scope: +type: decision +rationale: +impact: +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` diff --git a/memory-bank/glossary.md b/memory-bank/glossary.md new file mode 100644 index 00000000..8f6933ca --- /dev/null +++ b/memory-bank/glossary.md @@ -0,0 +1,79 @@ +# Glossary + +## Entry Template + +``` +date: YYYY-MM-DD +author: +scope: +type: glossary +rationale: +impact: +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 diff --git a/memory-bank/open-questions.md b/memory-bank/open-questions.md new file mode 100644 index 00000000..6f2e8b95 --- /dev/null +++ b/memory-bank/open-questions.md @@ -0,0 +1,57 @@ +# Open Questions + +## Entry Template + +``` +date: YYYY-MM-DD +author: +scope: +type: question +rationale: +impact: +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 diff --git a/memory-bank/patterns.md b/memory-bank/patterns.md new file mode 100644 index 00000000..8734e940 --- /dev/null +++ b/memory-bank/patterns.md @@ -0,0 +1,66 @@ +# Patterns + +## Entry Template + +``` +date: YYYY-MM-DD +author: +scope: +type: pattern +rationale: +impact: +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` diff --git a/memory-bank/pitfalls.md b/memory-bank/pitfalls.md new file mode 100644 index 00000000..36aa35cd --- /dev/null +++ b/memory-bank/pitfalls.md @@ -0,0 +1,62 @@ +# Pitfalls + +## Entry Template + +``` +date: YYYY-MM-DD +author: +scope: +type: pitfall +rationale: +impact: +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. diff --git a/memory-bank/productContext.md b/memory-bank/productContext.md new file mode 100644 index 00000000..31bf49f0 --- /dev/null +++ b/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. diff --git a/memory-bank/projectbrief.md b/memory-bank/projectbrief.md new file mode 100644 index 00000000..b86c1a7d --- /dev/null +++ b/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. diff --git a/memory-bank/refactor-backlog.md b/memory-bank/refactor-backlog.md new file mode 100644 index 00000000..5f7109d1 --- /dev/null +++ b/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) diff --git a/memory-bank/systemPatterns.md b/memory-bank/systemPatterns.md new file mode 100644 index 00000000..13606728 --- /dev/null +++ b/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. diff --git a/memory-bank/techContext.md b/memory-bank/techContext.md new file mode 100644 index 00000000..1913be50 --- /dev/null +++ b/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