Robert Bond
ecd6075c3a
Related work items: #22570, #22576, #22577, #22583, #22586, #22587, #22588, #22590, #22591
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.
|