robbond/pedwfrontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(refactor): commit current refactor branch updates and slice1 xml/form derivation extraction

Browse Source
This commit is contained in:
robbond
2026-04-10 09:39:28 +01:00
parent bd3d311cfb
commit e9d4b65a3d
28 changed files with 1340 additions and 439 deletions
Download Patch File Download Diff File Expand all files Collapse all files
context/current-state-scorecard.md
-35
View File
@@ -1,35 +0,0 @@
# Current State Scorecard (2026-03-25)
Purpose: provide a single operational view of architecture/debt progress with evidence references.
## RAG Legend
- Green: materially addressed for current stream
- Amber: partial progress, follow-on needed
- Red: unresolved/high risk remains
## Scorecard
| Area | Status | Current position | Evidence |
| --------------------------------- | ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| API contract consistency | Green | Large endpoint clusters normalized on structured contracts with phase21 coverage. | `memory-bank/change-log.md` (endpoint hardening stream), `tests/phase21/endpoint-handler-contract.test.cjs` |
| Actions/service decomposition | Amber | Shared clients and route builders introduced; monolith risk reduced but full domain split remains. | `actions/clients/*`, `actions/services/*`, `memory-bank/debt-list.md` |
| Endpoint sprawl/proxy duplication | Amber | Shared relay forwarding and helper reuse reduced duplication; long-tail handlers still exist. | `pages/api/middleware/relayForwarding.js`, `context/architecture.md` |
| High-risk automation | Green | Focused checks now cover auth redirect safety, signed-delete/upload negatives, and EN/CY rewrite parity. | `tests/phase22/auth-redirect-safety.test.cjs`, `tests/phase22/i18n-route-parity.test.cjs`, `tests/phase22/index.test.cjs` |
| i18n parity assurance | Amber | Targeted parity checks in place; CI-level parity enforcement still pending. | `tests/phase22/i18n-route-parity.test.cjs`, `context/architecture.md` |
| Logging redaction consistency | Amber | Relay-side structured redaction improved; broader auth/email/file logging hardening remains open. | `memory-bank/open-questions.md` (Q-001), `context/architecture.md` |
| Runtime canonicalization | Red | `server.js` and `server/server.js` ambiguity not yet formally closed. | `memory-bank/architect-review.md`, `context/architecture.md` |
## Next execution focus
1. Sequence B: signed-request consolidation + logging hardening.
2. Sequence C: CI-level i18n parity gates + endpoint long-tail reduction.
3. Runtime canonicalization decision with explicit operational owner.
## Update cadence
- Update after every non-trivial architecture/debt slice.
- Keep this file aligned with:
- `context/architecture.md`
- `memory-bank/debt-list.md`
- `memory-bank/change-log.md`
context/newappeal-factor-guardrails.md
+117
View File
@@ -0,0 +1,117 @@
# New Appeal Refactor Guardrails
## Purpose
These guardrails apply to all AI-assisted and human-assisted work on the refactor branch for the new appeal flow.
## Critical Rule
Preserve the current live S78 behaviour unless the task explicitly requires a behaviour change.
Do not assume a cleaner implementation is allowed to alter behaviour.
## Protected Areas
Treat the following as protected flow files:
- `pages/newappeal/index.js`
- `pages/newappeal/[appealtypes].js`
- `components/newappeal/buildsection.js`
- `components/newappeal/buildchecksection.js`
- `components/newappeal/buildrow.js`
- `components/newappeal/buildfield.js`
- `components/newappeal/buildcheckrow.js`
- `components/newappeal/complete.js`
- `components/newappeal/aboutyou.js`
- `components/newappeal/createCase.js`
- any helpers or service modules used directly by save/progress/upload/submit/finalise logic
## Protected Behaviour
The following must not regress:
1. Start a new S78 appeal
2. Create case / initial journey entry
3. Section rendering from form definition
4. Section progression
5. Save and exit
6. Resume saved appeal
7. File/document upload behaviour
8. Check answers page
9. Appeal PDF generation/download path
10. Final submit/finalisation
11. Confirmation page behaviour
12. Email/notification side effects
13. English/Welsh parity for touched areas
## Required Refactor Approach
When refactoring:
1. Understand current behaviour first
2. Identify the smallest safe boundary
3. Prefer extraction of pure/helper logic
4. Keep public interfaces stable where possible
5. Avoid changing UI, business rules, and structure in one step
6. Keep each slice easy to review and revert
## Required Testing Mindset
Before changing critical flow behaviour, add or update protection such as:
- characterization tests for current behaviour
- targeted integration/service tests
- journey-level regression checks
- payload-shape assertions for save/submit/finalise paths
If automation is not practical yet, include an explicit manual verification matrix.
## Payload/Integration Safety
Do not change without explicit need:
- CRM payload field names or structure
- boolean/value normalization behaviour
- document/file metadata shape
- save/resume payload expectations
- PDF generation inputs
- notification template selection or personalisation structure
## i18n / Accessibility Safety
For touched user-facing behaviour:
- keep EN/CY behaviour aligned
- keep labels, messages, and route behaviour consistent
- preserve semantic structure, focus behaviour, and validation messaging
## Delivery Safety
Preferred pattern for each change:
1. protect current behaviour
2. extract one concern
3. run focused validation
4. keep rollback straightforward
5. merge only when safe
## What To Avoid
Do not:
- perform broad rewrites
- mix feature delivery with refactor work
- replace dynamic/config-driven logic with one-off hardcoding
- move many responsibilities at once
- introduce new dependencies unless clearly justified
- silently change business rules while “cleaning up”
## Refactor Success Criteria
A refactor slice is successful when it:
- preserves behaviour
- reduces complexity or coupling
- improves readability or testability
- keeps regression risk controlled
- remains small enough to merge safely into `SIPS-Development`
context/next-work-plan-sequence-b.md
-101
View File
@@ -1,101 +0,0 @@
# Sequence B Work Plan (2026-03-25)
Scope: implement the next architecture lane after Sequence A completion.
Sequence B objectives:
1. Consolidate signed-request patterns.
2. Harden logging policy in sensitive paths.
## Workstream B1: Signed-request consolidation
### Goal
Reduce duplicate hash/header/method composition logic across service modules without changing behavior contracts.
### Target scope
- `actions/services/portalDirectService.js`
- `actions/services/documentDirectService.js`
- `actions/services/caseDirectService.js` (if signed routes exist)
- shared client layer in `actions/clients/`
### Proposed implementation
1. Introduce a focused signed-request helper (or helper set) in `actions/clients/`:
- signed GET
- signed POST
- signed DELETE
2. Normalize hash/signing + header behavior through helper API.
3. Migrate in bounded slices (module by module), preserving current catch semantics.
### Acceptance criteria
- No route URL/signature behavior regressions.
- Existing signed flows preserve:
- hash generation behavior
- request method
- required headers
- error-return/catch contracts.
- Phase22 behavioural tests expanded where relevant.
### Validation checklist
- `node tests/phase22/index.test.cjs`
- `node tests/phase7/service-behaviour.test.cjs`
- `npm run lint`
### Rollback plan
- Revert helper adoption commit(s) for affected service only.
- Keep migrations bounded so each module rollback is isolated.
## Workstream B2: Logging hardening in sensitive paths
### Goal
Replace ad-hoc verbose logging in auth/email/file/account-sensitive paths with redacted, structured logs.
### Target scope
- `pages/api/auth/[...nextauth].js`
- selected `pages/api/email/**`
- selected `pages/api/file/**`
- any adjacent shared helper used by these routes
### Proposed implementation
1. Define/confirm minimal redaction policy (link to `memory-bank/open-questions.md` Q-001).
2. Introduce/standardize structured logger usage pattern for sensitive flows.
3. Replace high-risk direct logs in bounded route clusters.
### Acceptance criteria
- No secrets/tokens/personal data in new logs.
- Error correlation remains operationally useful.
- Existing route behavior/contracts unchanged.
### Validation checklist
- `npm run lint`
- targeted route-level negative-path checks for changed handlers
- manual review of log payload fields against redaction policy
### Rollback plan
- Revert logging-hardening commit(s) by cluster.
- Restore previous logger call sites if operational diagnostics regress.
## Delivery sequencing
1. B1 signed-request helper design + one pilot migration.
2. B1 full module rollout (portal/document, then any remaining signed paths).
3. B2 redaction policy confirmation.
4. B2 auth cluster hardening.
5. B2 file/email cluster hardening.
## Ownership and governance
- Track each slice in `memory-bank/change-log.md`.
- Record policy decisions in `memory-bank/decisions.md`.
- Escalate unresolved policy questions in `memory-bank/open-questions.md`.
context/onboarding-guide.md
-112
View File
@@ -1,112 +0,0 @@
# Engineer Onboarding Guide — PEDW FrontEnd
## 1) Project Overview
PEDW FrontEnd is the Planning and Environment Decisions Wales (PEDW) portal for discovering planning appeals and accessing personalised casework journeys. It supports public search/browse and authenticated dashboard workflows, with strong accessibility and bilingual (English/Welsh) requirements.
## 2) Technology Stack
- **Frontend:** Next.js 14 (Pages Router), React 18
- **Language:** Primarily JavaScript (some TypeScript tooling present)
- **State:** Redux, `next-redux-wrapper`, `redux-persist`, `redux-thunk`, `redux-form`
- **Auth:** `next-auth` + Prisma adapter (email magic-link flow)
- **Auth data layer:** Prisma + SQL Server (`prisma/schema.prisma`) for next-auth identity/session tables
- **Portal business data layer:** Dynamics 365 CRM queried via REST + OData through frontend API routes
- **i18n:** `next-translate` + `i18n.js` + Welsh rewrites in `next.config.js`
- **Integrations:** Azure Service Bus Relay (CRM transport), Azure Blob/Queue, GOV.UK Notify, Application Insights, mapping (Leaflet/google-map-react), PDF generation
## 3) Architecture Overview
- Active runtime is **Next.js runtime** (legacy custom server files exist but are inactive).
- UI routes and APIs live in `pages/` and `pages/api/**`.
- Security controls are applied through `middleware.js` + security headers in `next.config.js`.
- Auth/session logic is centralized in `pages/api/auth/[...nextauth].js`.
- Shared integration/service logic sits mostly in `actions/` (notably large `actions/index.js`).
- Portal data calls are sent from `pages/api/endpoint/**` to Dynamics 365 CRM through Azure Service Bus Relay.
- For relay-bound calls, a hash is generated from request path (excluding domain) and appended; relay validates using the same shared hash key.
## 4) Repository Structure
- `pages/` — routes + API handlers
- `components/` — UI/features (case, DNS, account, admin, mapping, PDF templates)
- `actions/` — API client and side-effect helpers
- `lib/` — reusable form/domain helpers
- `store/` — Redux reducers/store setup/hydration/persistence
- `prisma/` — schema + migrations
- `locales/` — EN/CY translations
- `data/` — lookup and form metadata files
- `tests/` — test area (appears limited)
- `server/`, `server.js` — legacy/inactive runtime artifacts
## 5) Core System Components
- **Public search/case flows:** basic search (`/search`), advanced search (`/advancedsearch`), and address search (`/addresssearch`) with result pages and case detail/document UIs
- **Account/auth:** next-auth email verification and Prisma-backed sessions
- Portal routes (`/myportal/**`): user-specific case/representation/watchlist workflows
- **File/doc pipeline:** upload/download/blob flows and PDF generation under `pages/api/file/**`
- **Notifications:** GOV.UK Notify integrations under `pages/api/email/**` + auth email provider
## 5a) User Involvement / Role Model
- Newly registered/authenticated users default to **Interested Party** involvement.
- Users who raise a new appeal become **Appellants**.
- CRM contact constraints allow only one role type; once Appellant is assigned, it remains their role.
- **Agents** can submit appeals on behalf of multiple Appellants.
- **LPA (Local Planning Authority)** users are a separate persona with a distinct dashboard view.
- LPA dashboards focus on appeals within that authority.
- LPA users cannot raise appeals (option is hidden), but they can submit representations.
## 6) Data Model
Prisma schema is focused on next-auth persistence (SQL Server):
- `User`
- `Account`
- `Session`
- `VerificationToken`
Datasource is SQL Server (`DATABASE_URL`). This model underpins authentication/session behavior and should be treated as sensitive core infrastructure. Portal business/case data is sourced separately from Dynamics 365 CRM via relay-backed API calls.
## 7) Key Workflows
- **Sign-in:** user requests magic link -> email via Notify -> callback/session via next-auth.
- **Search journey:** frontend query -> `pages/api/endpoint/**` proxy endpoint(s) -> path hash appended -> Azure Service Bus Relay (validates hash with shared key) -> Dynamics 365 CRM (REST/OData) -> normalized UI rendering.
- **Case summary to representation:** user selects case reference from results -> lands on case summary -> “make representation” shown only when criteria/date rules allow -> user can start flow but must be authenticated to submit.
- **Dashboard journey (`/myportal`):** signed-in users can raise new appeals, search appeals, view watched cases, view partially completed appeals, view submitted appeals, and manage submitted/partially submitted representations.
- **Role behavior:** default involvement starts as Interested Party; new appeal creation sets Appellant role (persistent due to CRM single-role contact model); Agent users may act for multiple Appellants.
- **LPA dashboard behavior:** LPA users see an authority-scoped dashboard, do not see raise-appeal options, and can raise representations on existing appeals.
- **Document workflow:** user upload/submit -> blob storage + metadata updates -> PDF/document retrieval.
- **Bilingual routing:** Welsh aliases rewired in `next.config.js`, locale resources in `locales/en|cy`, page namespace mapping in `i18n.js`.
## 8) Development Workflow
From scripts and runbook:
- `npm run dev` — local dev
- `npm run build` + `npm start` — production build/start
- `npm run lint` — baseline validation
Expected change protocol emphasizes:
- scoped changes,
- EN/CY parity checks,
- accessibility smoke checks,
- negative-path checks on sensitive flows,
- memory-bank/log updates for non-trivial changes.
## 9) Observed Conventions
- 4-space indentation, no trailing commas (per local conventions)
- Keep page-level logic thin where possible; place reusable logic in `lib/`/`components/`/`actions/`
- API naming pattern commonly uses `*_api.js`
- Heavy use of proxy-style API handlers
- Existing AI governance artifacts define guardrails (`.clinerules`, `GUARDRAILS.md`, `context/`, `memory-bank/`)
## 10) Potential Risks / Weak Areas
1. **Large `actions/index.js` coupling** (many responsibilities in one module)
2. **API contract inconsistency** (error/response handling varies across endpoints)
3. **Extensive `console.log` footprint** (signal/noise and potential sensitive logging concerns)
4. **Duplication across API proxy handlers** (token/header/hash/relay logic repeated)
5. **i18n complexity drift risk** (rewrite + locale namespace parity maintenance)
6. **Limited automated tests for high-risk flows** (manual validation burden)
context/project-overview.md
-88
View File
@@ -1,88 +0,0 @@
# PEDW FrontEnd Project Overview
## Purpose
PEDW FrontEnd is a public-service web platform for planning casework and DNS (Developments of National Significance) journeys, with public search and citizen self-service plus authenticated portal/admin capabilities.
## Current Stack
- **Frontend:** Next.js 14 (`pages` router), React 18
- **Server runtime:** Next.js runtime (legacy server files remain in-repo but are not used)
- **State:** Redux + `next-redux-wrapper` + `redux-persist`
- **Auth:** `next-auth` with Prisma adapter and email sign-in flow
- **Auth persistence:** Prisma + SQL Server schema (`prisma/schema.prisma`) for next-auth tables
- **Portal case data source:** Microsoft Dynamics 365 CRM (queried via REST + OData)
- **Portal API transport path:** Frontend API routes -> Azure Service Bus Relay -> Dynamics 365 CRM
- **Relay request integrity:** Forwarded API calls include a hash derived from request path (excluding domain). Relay recomputes hash with shared key and rejects mismatches.
- **i18n:** `next-translate`, locales `en` and `cy`, Welsh rewrites in `next.config.js`
- **Integrations:** Azure storage/queues, GOV.UK Notify, Application Insights, mapping, PDF generation
## Repository Shape (Intent)
- `pages/`: routes and API handlers (`pages/api/**`)
- `components/`: UI and feature components (case, account, admin, mapping, PDF templates)
- `actions/`: API client + shared side-effect logic
- `lib/`: reusable domain helpers and form-related logic
- `store/`: Redux reducers/store hydration/persistence
- `prisma/`: schema and migrations
- `locales/`: translation resources (EN/CY)
- `server/` + root `server.js`: legacy runtime files retained in repository
## Core User/Business Areas
1. Public appeal discovery via:
- basic search (`/search`)
- advanced search (`/advancedsearch`)
- address search (`/addresssearch`)
2. Search results and case summary journey (case reference selection -> summary page)
3. Representation flow from case summary (criteria/date dependent “make representation” action)
4. Passwordless authentication via next-auth magic links for authenticated submissions
5. Authenticated dashboard (`/myportal/**`) for personalised casework
6. New appeal and representation lifecycle management (partial + submitted states)
7. Admin/document workflows
## Planning Casework Portal Dashboard (My Portal)
The Planning Casework dashboard is the authenticated Appellant/Interested party user’s operational home page for:
- starting new appeal submissions
- Viewing the users submitted appeals
- finding existing cases quickly
- resuming in-progress submissions
- monitoring submitted cases/representations
- tracking watched cases
- Information to view infrastructure project activity
The Planning Casework dashboard is the authenticated LPA user’s operational home page for:
- finding existing cases quickly
- resuming in-progress submissions
- monitoring submitted cases/representations
- tracking watched cases
- Information to view infrastructure project activity
The dashboard is organized into task-focused panels that separate **action entry points** (for example, “Make a new appeal”, “Search for a case”) from **state-based worklists** (for example, “Appeals awaiting submission”, “My cases”, and representation lists).
## Public Basic Search Results (Search Journey)
In the public case-discovery journey, the basic search results page provides a structured list of matched cases and key metadata. The page supports sorting and pagination, links each case reference through to case detail, and presents a clear no-results or loading/error state when appropriate.
Results content is locale-aware (EN/CY labels and formatted values) and includes highlighted query matches in key visible fields where supported by returned data.
## User Involvement Model (Portal)
- Newly registered/authenticated portal users default to **Interested Party** involvement.
- Users who raise a new appeal become **Appellants**.
- CRM contact constraints allow only one role type, so once set to Appellant this remains their role.
- **Agents** can submit appeals on behalf of multiple Appellants.
- **LPA (Local Planning Authority)** users have a distinct persona/dashboard view scoped to appeals raised within their authority.
- LPA users do **not** see the “raise appeal” option.
- LPA users can still make/submit representations on appeals.
## Operating Constraints
- Public-sector reliability expectations: avoid regressions on live service paths.
- Bilingual parity is mandatory for user-facing route/content changes.
- Accessibility expectations are high (keyboard and semantic behavior).
- Security-sensitive areas include auth/session, uploads/documents, notifications, and account data.
- Distinguish data paths: next-auth identity/session data is persisted in SQL Server; portal business data is sourced from Dynamics 365 CRM via relay-backed API calls with request-path hash validation.
context/refactor-branch-charter.md
+90
View File
@@ -0,0 +1,90 @@
# Refactor Branch Charter — New Appeal Flow
## Purpose
This branch exists to safely refactor the live new appeal flow so it is easier to maintain, safer to change, and better prepared to support additional appeal types beyond the current S78 planning appeal flow.
This is a **behaviour-preserving refactor branch**, not a feature branch.
## Primary Goal
Create a safer internal structure for the new appeal flow while preserving current live behaviour for the S78 appeal journey.
## Why This Branch Exists
The current new appeal implementation has grown over time to meet business need and now contains a mix of:
- page composition
- flow orchestration
- XML-driven form rendering
- validation
- file/document handling
- progress/save logic
- submission/finalisation logic
- integration shaping for CRM, PDF generation, and notifications
This branch exists to improve those boundaries incrementally without disrupting the live service.
## Scope
In scope:
- behaviour-preserving refactor of `pages/newappeal/**` and `components/newappeal/**`
- extraction of reusable workflow logic from UI-heavy components
- improved boundaries between rendering, workflow, and integration logic
- regression test coverage for critical S78 journeys
- preparing the codebase for future appeal-type extensibility
Out of scope unless explicitly requested:
- business rule changes
- visual redesign
- broad framework/library migration
- replacing working dynamic form behaviour with hardcoded appeal-specific logic
- changes to live BAU behaviour beyond strictly necessary bug fixes
## Branch Relationship to BAU
- BAU continues on `SIPS-Development`
- this branch is the protected refactor lane
- safe, proven slices may be merged back into `SIPS-Development` when ready
- urgent live fixes should go to `SIPS-Development` first, then be synced into this branch
## Non-Negotiable Principles
1. Preserve live S78 behaviour unless explicitly told otherwise.
2. Prefer extraction over rewrite.
3. Prefer small, mergeable slices over long-lived hidden change.
4. Add or update regression protection before changing critical flow logic.
5. Keep English/Welsh behaviour aligned.
6. Treat save/resume/upload/check/submit/complete as protected journey stages.
## Target Direction
The long-term direction is:
- shared new appeal workflow engine
- appeal-type definitions/configuration separated from UI rendering
- smaller, clearer components
- isolated validation and payload-shaping logic
- safer addition of future appeal types through definition + bounded type-specific rules
## Definition of Success
This branch is succeeding when:
- core S78 journey behaviour remains stable
- regression confidence increases
- high-risk logic moves out of large render-heavy components
- new appeal code becomes easier to understand and test
- future appeal types can be added with less change to core flow code
## Working Branch Model
This refactor stream uses the `refactor` branch as its working base.
- BAU continues on `SIPS-Development`
- refactor work is performed from `refactor`
- safe refactor slices may later be merged into `SIPS-Development`
This branch should not be treated as BAU, and BAU should not be treated as the refactor workspace.
context/refactor-tracker.md
+104
View File
@@ -0,0 +1,104 @@
# New Appeal Refactor Tracker
Base branch for this tracker: `refactor`
## Status
Current slice: Slice 1 — XML/Form Derivation Extraction
Status: NOT STARTED
---
## Slice List
### Slice 1 — XML/Form Derivation Extraction
Status: NOT STARTED
- Extract XML parsing helpers into lib
- Keep selectors identical
- No behaviour change
---
### Slice 2a — Payload Cleanup Helpers
Status: NOT STARTED
- Extract boolean normalization
- Extract null/internal key stripping
---
### Slice 2b — File Merge/Dedupe Helpers
Status: NOT STARTED
- Extract file list merge logic
- Extract dedupe logic
---
### Slice 3 — Side Effect Facade
Status: NOT STARTED
- Wrap existing service calls
- No logic changes
---
### Slice 4 — BuildSection UI Extraction
Status: NOT STARTED
---
### Slice 5 — BuildCheckSection UI Extraction
Status: NOT STARTED
---
### Slice 6 — BuildCheckRow Formatter Map
Status: NOT STARTED
---
### Slice 7 — Props Boundary Cleanup
Status: NOT STARTED
---
### Slice 8 — Start Flow Cleanup (CreateCase / AboutYou)
Status: NOT STARTED
---
## Rules
- Only work on ONE slice at a time
- Do not move to next slice until current is COMPLETE
- Do not combine slices
- Preserve behaviour at all times
## Notes
- Save/resume payload shape is sensitive
- File upload logic duplicated in multiple places
- BuildSection is highest risk area
## Regression Checklist (Run After Each Slice)
- Start new appeal
- Save and exit
- Resume saved appeal
- Navigate sections
- Upload file
- View check answers
- Submit appeal (if safe to test)
- View confirmation page
- Verify EN/CY parity