Files

T

Robert Bond 37a81522d5 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...

2026-04-20 13:09:07 +00:00

3.0 KiB

Raw Blame History

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

Preserve live behaviour
Prefer extraction over rewrite
Work in small, safe slices
Keep changes reversible
Protect:
- save/resume flows
- upload behaviour
- submission/finalisation
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:

follow slice-based approach
implement one concern per slice
validate behaviour after each slice
merge into refactor only when safe
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.

3.0 KiB Raw Blame History Unescape Escape