robbond/pedwfrontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
SIPS-Development
pedwfrontend/context/representations-refactor-tracker.md
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

6.4 KiB
Raw Permalink Blame History

Representations Refactor Tracker

Base branch: refactor

Status

Current slice: Slice R9 — Summary Rollout (Batch 1)
Status: COMPLETE

Slice List

Slice R1 — Representation Entry Logic Extraction

Status: COMPLETE

Notes: Completed in prior refactor slice work; no additional changes required in this closeout.

Slice R2 — Representation Page Loader Separation

Status: COMPLETE

Notes: Completed in prior refactor slice work; no additional changes required in this closeout.

Slice R3 — Journey Step Resolution Extraction

Status: COMPLETE

Notes: Completed in prior refactor slice work; no additional changes required in this closeout.

Slice R4 — Flow Shell Decomposition

Status: COMPLETE

Notes: Completed in prior refactor slice work; no additional changes required in this closeout.

Completion notes (this slice):

  • Implemented on feature branch created from refactor: rep-slice-r4-flow-shell.
  • Extracted render-shell structure from components/case/representation/index.js into:
    • components/case/representation/shell/RepresentationFlowFormStage.js
    • components/case/representation/shell/RepresentationTimetablePanel.js
  • Kept index.js as orchestration owner (no side-effect migration):
    • onHandleSubmit unchanged in location/ownership
    • updateRepresentation unchanged in location/ownership
    • upload/PDF/email sequencing unchanged
    • stage-resolution/questionnaire decisions remain in index.js
  • Preserved explicit prop passing; no grouped-prop/view-model abstraction introduced in this slice.
  • Validation evidence:
    • npm run lint completed (warnings only, no new errors).
    • npm run test:reps completed: 6 passed.
    • Manual APP/IP/Agent/LPA checks: passed.
    • Manual EN/CY parity checks: passed.

Slice R5 — Representation Elements Normalisation

Status: COMPLETE

Notes: Completed in prior refactor slice work; no additional changes required in this closeout.

Slice R6 — Async Data / Service Layer Cleanup

Status: COMPLETE

Notes: Completed in prior refactor slice work; no additional changes required in this closeout.

Slice R7 — Summary / Case-Type Rendering Simplification (Proof Slice)

Completion notes (this slice):

  • Implemented on feature branch created from refactor: rep-slice-r7-summary-rendering-simplification.
  • Added render-only summary primitives:
    • components/case/summary/components/SummaryCard.js
    • components/case/summary/components/SummaryRow.js
  • Applied to proof subset:
    • pinswg_planningappeals78id.js
    • pinswg_planningconditionss73s79id.js
  • Preserved constraints:
    • no translation/date/bilingual logic moved
    • no linked-cases extraction
    • no ordering/visibility changes
  • Validation evidence:
    • npm run lint passed (warnings only)
    • npm run test:reps passed (7 passed)
    • manual APP/IP/Agent/LPA + EN/CY checks passed

Slice R8 — Submission / Finalisation Boundary Isolation

Completion notes (this slice):

  • Implemented on feature branch created from refactor: rep-slice-r8-finalisation-boundary.
  • Added helper module:
    • components/case/representation/utils/finalisationBoundary.js
  • Extracted:
    • buildRepresentationUpdateBody(...)
    • buildSubmitEnrichedValues(...)
    • runFinalisationSequence(...)
  • Preserved:
    • parent-owned branching logic
    • completion-side effects in representationComplete.js
    • exact sequencing of finalisation operations
  • Validation evidence:
    • npm run lint passed (warnings only)
    • npm run test:reps passed (7 passed)
    • manual APP/IP/Agent/LPA + EN/CY checks passed

Slice R9 — Summary Rollout (Batch 1)

Goal: Roll out proven summary rendering primitives across remaining low-risk summary-type files.

Completion notes (this slice):

  • Applied SummaryCard and SummaryRow primitives to Batch 1 summary-type files.
  • Rollout executed incrementally:
    • one summary-type file per commit
    • consistent mechanical application of proven pattern
  • Changes limited strictly to presentational structure:
    • replaced card shell markup with SummaryCard
    • replaced row wrapper markup with SummaryRow where safe
  • Preserved across all updated files:
    • field visibility rules
    • row and card ordering
    • translation key selection
    • EN/CY branching behaviour
    • date source selection and formatting
    • linked-case logic
    • route/query behaviour
    • payloads and Redux state
  • Parent summary-type files retain all business logic and conditional rendering.
  • Shared components confirmed render-only.

Validation evidence:

  • npm run lint completed (warnings only, no new errors)
  • npm run test:reps passed (7 passed)
  • Structured validation confirmed:
    • translation/bilingual logic unchanged
    • date/lookup logic unchanged
    • conditional rendering preserved
  • Targeted manual spot-checks completed:
    • pinswg_sipscase.js
    • pinswg_dnsid.js
    • pinswg_electricityactid.js
    • pinswg_harbourrevisionorderid.js
  • No behavioural regressions identified

Outcome:

  • Summary rendering layer simplified and standardised
  • Duplication reduced while preserving all behaviour
  • Safer and more maintainable structure

Status: COMPLETE

Rules

  • Only work on ONE slice at a time
  • Do not combine slices
  • One branch per slice (exception: controlled rollout batches)
  • One commit per slice (or per file in rollout batch)
  • Update tracker after slice completion
  • Do not proceed if regression risk exists

Regression Checklist (Run After Each Slice)

Core Journey

  • Navigate from case summary → Make representation
  • Select capacity
  • Select representation type
  • Enter content
  • Upload files (if applicable)
  • View check answers
  • Submit representation
  • View confirmation page

Validation

  • EN/CY parity maintained
  • No navigation regressions
  • No state inconsistencies
  • No console errors

Technical

  • npm run lint passes
  • No new warnings/errors introduced

Notes

  • CaseSummary is a high-risk entry point
  • Eligibility logic is complex and must not drift
  • Submission flow is highly sensitive
  • Dual-mode entry (new vs existing representation) is a key complexity

Definition of Done (Per Slice)

A slice is complete when:

  • behaviour is preserved
  • regression checks pass
  • code is cleaner and easier to understand
  • change is small and safe to merge
Reference in New Issue View Git Blame Copy Permalink