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...
2.8 KiB
2.8 KiB
Representations Refactor Guardrails
Purpose
These guardrails apply to all work on the representations refactor stream.
This stream follows the same discipline as the new appeal refactor:
Behaviour-preserving, slice-based refactor of a live journey.
Critical Rule
Preserve the current live behaviour of the representations journey.
Do not assume a cleaner implementation allows behaviour changes.
Protected Journey
The following user journey must not regress:
- Enter case summary page
- Click Make representation / consultation
- Navigate to representation flow
- Select capacity
- Select representation type
- Enter content and upload files
- View check answers
- Submit representation
- View completion/confirmation
Protected Behaviour
Do not change:
- representation eligibility logic (dates, appeal type, specialist process)
- CTA visibility and routing from case summary
- capacity selection behaviour
- representation type branching
- validation rules and messaging
- payload shape sent to backend/CRM
- file upload handling and metadata
- submission/finalisation flow
- confirmation behaviour
- navigation order or step progression
- route/query parameters
- EN/CY behaviour
Refactor Approach
When refactoring:
- Understand current behaviour first
- Identify smallest safe boundary
- Prefer extraction over rewrite
- Keep interfaces stable
- Avoid mixing concerns in one change
- Keep slices small and reversible
Required Testing Mindset
Before completing any slice:
- manually walk the full representation journey
- verify:
- start from case summary CTA
- capacity → type → content → check → submit
- successful completion
- verify EN/CY parity
- verify no navigation or state regression
If behaviour cannot be confidently verified: → do not proceed
Payload / Integration Safety
Do not change without explicit requirement:
- CRM payload structure
- field names or mapping
- document/file metadata shape
- blob storage structure
- submission API behaviour
i18n / Accessibility Safety
For any user-facing change:
- maintain EN/CY parity
- do not change translation keys unless required
- preserve accessibility semantics and structure
- maintain focus and validation behaviour
What To Avoid
Do not:
- rewrite large components in one step
- introduce new business rules
- hardcode dynamic logic
- mix refactor with feature work
- change multiple concerns in one slice
Refactor Success Criteria
A slice is successful when:
- behaviour is unchanged
- complexity is reduced
- readability is improved
- regression risk is controlled
- change is small and reviewable
One-Line Rule
If in doubt:
Keep behaviour the same, reduce risk, and make the smallest safe change.