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
@@ -0,0 +1,300 @@
|
||||
# Representations Refactor — Current State of Play
|
||||
|
||||
## Purpose
|
||||
|
||||
This document captures the **pre-refactor state** of the representations flow and defines the starting point for the behaviour-preserving refactor stream.
|
||||
|
||||
It mirrors the approach used for the new appeal refactor and will be updated as slices are completed.
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The representations flow is:
|
||||
|
||||
- functionally complete and live
|
||||
- behaviourally stable
|
||||
- structurally complex and tightly coupled
|
||||
|
||||
The flow currently:
|
||||
|
||||
- spans multiple entry points
|
||||
- mixes UI, workflow, and data logic
|
||||
- contains duplicated branching and rendering logic
|
||||
- relies heavily on shared global state (`currentView`, `searchResultsObj`)
|
||||
|
||||
---
|
||||
|
||||
## Journey Overview
|
||||
|
||||
The user journey is:
|
||||
|
||||
1. Navigate to case summary page
|
||||
2. Click **Make representation / consultation**
|
||||
3. Enter representation flow
|
||||
4. Select capacity
|
||||
5. Select representation type
|
||||
6. Enter content and upload files
|
||||
7. Review check answers
|
||||
8. Submit representation
|
||||
9. View confirmation/completion
|
||||
|
||||
---
|
||||
|
||||
## Entry Points
|
||||
|
||||
### Primary Entry
|
||||
|
||||
- `CaseSummary` component
|
||||
- CTA button logic determines:
|
||||
- whether representation is allowed
|
||||
- which label to display
|
||||
- which route to navigate to
|
||||
|
||||
### Route
|
||||
|
||||
- `/myportal/representation?case=<caseRef>`
|
||||
|
||||
---
|
||||
|
||||
## Dual Mode Behaviour (Critical)
|
||||
|
||||
The flow operates in two modes:
|
||||
|
||||
### 1. New Representation (from search/case)
|
||||
|
||||
- triggered from case summary CTA
|
||||
- loads case data via search + details APIs
|
||||
- initializes new representation state
|
||||
|
||||
---
|
||||
|
||||
### 2. Existing Representation (resume/edit)
|
||||
|
||||
- triggered via query param (`state`)
|
||||
- loads representation from blob storage
|
||||
- hydrates existing data and files
|
||||
|
||||
---
|
||||
|
||||
This dual-mode behaviour is a **major complexity driver**.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### High-Level Structure
|
||||
|
||||
- Page layer (SSR + Redux hydration)
|
||||
- Case component (core orchestration)
|
||||
- Representation flow components (capacity/type/content/check)
|
||||
- Shared helpers (`representationElements`)
|
||||
- Service layer (case data, blob storage, CRM integration)
|
||||
|
||||
---
|
||||
|
||||
### Key Components
|
||||
|
||||
- `CaseSummary` → entry + CTA logic
|
||||
- `Case` → main orchestration component
|
||||
- Representation flow components:
|
||||
- capacity selection
|
||||
- representation type selection
|
||||
- content entry
|
||||
- check answers
|
||||
- completion
|
||||
|
||||
---
|
||||
|
||||
### State Management
|
||||
|
||||
Primary state dependencies:
|
||||
|
||||
- `currentView`
|
||||
- `searchResultsObj`
|
||||
- `myRepresentations`
|
||||
- `filesForRepresentations`
|
||||
|
||||
Heavy reliance on deeply nested props.
|
||||
|
||||
---
|
||||
|
||||
## Current Architecture Issues
|
||||
|
||||
### 1. High Coupling
|
||||
|
||||
- UI, workflow logic, and data fetching are tightly mixed
|
||||
- large components handle multiple responsibilities
|
||||
|
||||
---
|
||||
|
||||
### 2. Deep Prop Chains
|
||||
|
||||
Examples:
|
||||
|
||||
- `props.currentView.caseReference.*`
|
||||
- `props.searchResultsObj.*`
|
||||
|
||||
This reduces readability and increases fragility.
|
||||
|
||||
---
|
||||
|
||||
### 3. Duplicated Logic
|
||||
|
||||
- appeal-type branching repeated across components
|
||||
- summary rendering duplicated by case type
|
||||
- representation form structure repeated across capacity types
|
||||
|
||||
---
|
||||
|
||||
### 4. Dual Entry Complexity
|
||||
|
||||
- separate logic paths for new vs existing representation
|
||||
- mixed within the same components
|
||||
|
||||
---
|
||||
|
||||
### 5. Async Data Complexity
|
||||
|
||||
- chained service calls:
|
||||
- `getCase`
|
||||
- `getPortalModuleDetails`
|
||||
- repeated across different contexts
|
||||
- hard to reason about and test
|
||||
|
||||
---
|
||||
|
||||
### 6. Inline Business Logic
|
||||
|
||||
- eligibility rules embedded in UI components
|
||||
- date checks and appeal-type logic duplicated
|
||||
- LPA-specific behaviour scattered
|
||||
|
||||
---
|
||||
|
||||
## Risk Areas
|
||||
|
||||
High-risk areas that require extra caution:
|
||||
|
||||
- CaseSummary eligibility logic
|
||||
- SSR/data-loading logic for representation page
|
||||
- submission/finalisation flow
|
||||
- file upload handling
|
||||
- dual-mode entry (new vs existing)
|
||||
- Redux hydration and state consistency
|
||||
|
||||
---
|
||||
|
||||
## Behavioural Constraints (Must Not Change)
|
||||
|
||||
- eligibility rules for making a representation
|
||||
- journey step order and navigation
|
||||
- validation rules and messaging
|
||||
- payload structure sent to backend/CRM
|
||||
- file upload and metadata behaviour
|
||||
- submission/finalisation behaviour
|
||||
- confirmation page behaviour
|
||||
- route/query parameter structure
|
||||
- EN/CY parity
|
||||
|
||||
---
|
||||
|
||||
## Comparison to New Appeal Flow
|
||||
|
||||
### Similarities
|
||||
|
||||
- step-based user journey
|
||||
- check answers before submission
|
||||
- file upload and validation steps
|
||||
- finalisation/confirmation stage
|
||||
|
||||
---
|
||||
|
||||
### Differences (Important)
|
||||
|
||||
- dual-mode entry (new vs existing)
|
||||
- more reliance on external data sources
|
||||
- less structured “engine” (more implicit logic)
|
||||
- heavier coupling to case summary and search flows
|
||||
|
||||
---
|
||||
|
||||
## Refactor Readiness
|
||||
|
||||
The flow is suitable for refactor because:
|
||||
|
||||
- behaviour is stable
|
||||
- clear boundaries can be identified
|
||||
- repeated patterns exist
|
||||
- appeal refactor provides a proven model
|
||||
|
||||
---
|
||||
|
||||
## Refactor Strategy
|
||||
|
||||
The refactor will follow a **slice-based, behaviour-preserving approach**:
|
||||
|
||||
1. Extract entry logic (CaseSummary)
|
||||
2. Separate SSR/data-loading concerns
|
||||
3. isolate step resolution logic
|
||||
4. decompose large components
|
||||
5. clean up shared helpers
|
||||
6. stabilize async/service layers
|
||||
7. isolate submission/finalisation
|
||||
|
||||
---
|
||||
|
||||
## Initial Slice Focus
|
||||
|
||||
### Slice R1 — Entry Logic Extraction
|
||||
|
||||
Target:
|
||||
|
||||
- representation eligibility logic in `CaseSummary`
|
||||
|
||||
Goal:
|
||||
|
||||
- reduce coupling
|
||||
- isolate decision logic
|
||||
- prepare for safe downstream refactor
|
||||
|
||||
---
|
||||
|
||||
## Validation Position
|
||||
|
||||
At start of refactor:
|
||||
|
||||
- behaviour is assumed correct
|
||||
- no structural isolation exists
|
||||
- regression testing is manual
|
||||
|
||||
Each slice must:
|
||||
|
||||
- prove behaviour unchanged
|
||||
- reduce complexity incrementally
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The representations flow is:
|
||||
|
||||
- behaviourally stable
|
||||
- structurally complex
|
||||
- suitable for controlled refactor
|
||||
|
||||
The goal is to:
|
||||
|
||||
- reduce coupling
|
||||
- improve clarity
|
||||
- enable safer future changes
|
||||
|
||||
without altering live behaviour.
|
||||
|
||||
---
|
||||
|
||||
## Next Step
|
||||
|
||||
Begin **Slice R1 — Representation Entry Logic Extraction**
|
||||
|
||||
Following strict guardrails and regression validation.
|
||||
Reference in New Issue
Block a user