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...
301 lines
5.8 KiB
Markdown
301 lines
5.8 KiB
Markdown
# 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.
|