Merged PR 2260: refactor(representations): complete slice-based refactor of representations flow
## Representations Refactor — Behaviour-Preserving Structural Improvements This PR delivers a full refactor of the representations flow, improving structure, readability, and maintainability while preserving all existing behaviour. The work was completed using a controlled, slice-based approach with strict guardrails and regression validation at each step. No changes have been made to user journeys, payloads, routing, or EN/CY behaviour. The result is a cleaner, more maintainable codebase with reduced coupling and clearer separation of concerns, ready for future enhancements without increased risk. --- ## What Was Done The refactor was delivered incrementally across the following slices: - **R1** — Representation entry logic extraction - **R2** — Page loader separation (SSR/data orchestration) - **R3** — Journey step resolution extraction - **R4** — Flow shell decomposition - **R5** — Representation elements normalisation - **R6** — Data/service layer cleanup - **R7** — Summary rendering proof slice - **R8** — Submission/finalisation boundary isolation - **R9** — Summary rollout (Batch 1) Each slice: - was isolated to a single concern - followed strict guardrails - was validated before merge Full detail is available in: `context/representations-refactor-tracker.md` --- ## Key Improvements - Reduced coupling across the representations journey - Separated data loading, orchestration, and rendering concerns - Simplified complex conditional logic into testable helpers - Standardised summary rendering using shared primitives (`SummaryCard`, `SummaryRow`) - Isolated submission/finalisation sequencing into explicit boundaries - Improved overall readability and maintainability --- ## Behaviour Preservation This refactor does **not** change: - User journeys (APP / IP / Agent / LPA) - Route and query behaviour - Payload contracts and API interactions - Redux state shape and usage - Validation rules and messaging - EN/CY behaviour - File upload / PDF / email sequencing - Linked-case logic All changes are structural only. --- ## Validation ### Automated - `npm run lint` — passed (warnings only, no new errors) - `npm run test:reps` — passed (7/7) ### Manual Validated end-to-end across: - APP - IP - Agent - LPA Including: - representation creation - editing/resuming representations - submission flow - confirmation/completion behaviour - summary rendering across case types - EN/CY parity --- ## Risk Management The refactor targeted several high-risk areas: - Case summary entry logic - Representation submission/finalisation sequencing - Dual-mode entry (new vs existing representation) Risk was controlled through: - small, incremental slices - one branch per slice - regression validation per slice - strict behaviour-preservation guardrails - controlled rollout for summary rendering changes --- ## Reviewer Guidance Suggested areas to focus on: - End-to-end representation journey (create → submit → complete) - S...
This commit is contained in:
Robert Bond
@@ -1,90 +1,161 @@
|
||||
# Refactor Branch Charter — New Appeal Flow
|
||||
# Refactor Branch Charter — Portal Journeys
|
||||
|
||||
## 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 branch exists to safely refactor **core portal journeys** so they are:
|
||||
|
||||
- easier to maintain
|
||||
- safer to change
|
||||
- better structured for future extensibility
|
||||
|
||||
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.
|
||||
Improve internal structure of portal workflows while preserving all current live behaviour.
|
||||
|
||||
## 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:
|
||||
### 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
|
||||
- behaviour-preserving refactor of:
|
||||
- new appeal flow (`pages/newappeal/**`, `components/newappeal/**`)
|
||||
- representations flow (case summary → representation journey)
|
||||
- extraction of reusable workflow logic
|
||||
- improved separation between:
|
||||
- UI
|
||||
- workflow orchestration
|
||||
- data fetching
|
||||
- integrations
|
||||
- preparation for future extensibility
|
||||
|
||||
Out of scope unless explicitly requested:
|
||||
---
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- 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
|
||||
- UI redesign
|
||||
- payload/schema changes
|
||||
- replacing dynamic/config-driven logic with hardcoding
|
||||
- feature delivery mixed with refactor work
|
||||
|
||||
## 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
|
||||
## Branch Model
|
||||
|
||||
### Roles
|
||||
|
||||
- `SIPS-Development`
|
||||
- BAU branch
|
||||
- ongoing production work
|
||||
|
||||
- `refactor`
|
||||
- refactor integration branch
|
||||
|
||||
- feature branches
|
||||
- created from `refactor`
|
||||
- one per slice
|
||||
|
||||
---
|
||||
|
||||
### Flow
|
||||
|
||||
SIPS-Development → refactor → slice branches → refactor → SIPS-Development
|
||||
|
||||
---
|
||||
|
||||
## Refactor Streams
|
||||
|
||||
### 1. New Appeal Flow (Completed)
|
||||
|
||||
- Slice-based refactor (Slices 1–8)
|
||||
- Behaviour preserved (S78)
|
||||
- Improved structure and maintainability
|
||||
|
||||
This serves as the **reference model for future refactors**
|
||||
|
||||
---
|
||||
|
||||
### 2. Representations Flow (Active)
|
||||
|
||||
Scope includes:
|
||||
|
||||
- Case summary entry (CTA logic)
|
||||
- Representation journey:
|
||||
- capacity selection
|
||||
- representation type
|
||||
- content entry
|
||||
- file upload
|
||||
- check answers
|
||||
- submission
|
||||
- completion
|
||||
- SSR/data loading and Redux hydration
|
||||
- integration points (CRM, blob storage)
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
1. Preserve live behaviour
|
||||
2. Prefer extraction over rewrite
|
||||
3. Work in small, safe slices
|
||||
4. Keep changes reversible
|
||||
5. Protect:
|
||||
- save/resume flows
|
||||
- upload behaviour
|
||||
- submission/finalisation
|
||||
6. Maintain EN/CY parity
|
||||
|
||||
---
|
||||
|
||||
## Target Direction
|
||||
|
||||
The long-term direction is:
|
||||
Move towards:
|
||||
|
||||
- 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
|
||||
- shared journey/workflow engine
|
||||
- smaller, composable components
|
||||
- clear separation of:
|
||||
- decision logic
|
||||
- rendering
|
||||
- integration logic
|
||||
- ability to support:
|
||||
- multiple appeal types
|
||||
- additional portal journeys (like representations)
|
||||
|
||||
---
|
||||
|
||||
## Definition of Success
|
||||
|
||||
This branch is succeeding when:
|
||||
This branch is successful 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
|
||||
- behaviour is preserved across all journeys
|
||||
- complexity is reduced
|
||||
- code is easier to understand and change
|
||||
- regression risk is lower
|
||||
- new journeys/types can be added safely
|
||||
|
||||
## Working Branch Model
|
||||
---
|
||||
|
||||
This refactor stream uses the `refactor` branch as its working base.
|
||||
## Delivery Model
|
||||
|
||||
- BAU continues on `SIPS-Development`
|
||||
- refactor work is performed from `refactor`
|
||||
- safe refactor slices may later be merged into `SIPS-Development`
|
||||
Each refactor stream must:
|
||||
|
||||
This branch should not be treated as BAU, and BAU should not be treated as the refactor workspace.
|
||||
1. follow slice-based approach
|
||||
2. implement one concern per slice
|
||||
3. validate behaviour after each slice
|
||||
4. merge into `refactor` only when safe
|
||||
5. merge to `SIPS-Development` only when stable
|
||||
|
||||
---
|
||||
|
||||
## Safety Reminder
|
||||
|
||||
This is a live system.
|
||||
|
||||
If there is any doubt:
|
||||
|
||||
> Preserve behaviour, reduce risk, and keep changes small.
|
||||
|
||||
Reference in New Issue
Block a user