Robert Bond
37a81522d5
## 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...
162 lines
3.0 KiB
Markdown
162 lines
3.0 KiB
Markdown
# Refactor Branch Charter — Portal Journeys
|
||
|
||
## Purpose
|
||
|
||
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
|
||
|
||
Improve internal structure of portal workflows while preserving all current live behaviour.
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
### In Scope
|
||
|
||
- 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
|
||
|
||
- business rule changes
|
||
- UI redesign
|
||
- payload/schema changes
|
||
- replacing dynamic/config-driven logic with hardcoding
|
||
- feature delivery mixed with refactor work
|
||
|
||
---
|
||
|
||
## 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 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
|
||
|
||
Move towards:
|
||
|
||
- 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 successful when:
|
||
|
||
- 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
|
||
|
||
---
|
||
|
||
## Delivery Model
|
||
|
||
Each refactor stream must:
|
||
|
||
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.
|