Robert Bond
ecd6075c3a
Related work items: #22570, #22576, #22577, #22583, #22586, #22587, #22588, #22590, #22591
162 lines
3.0 KiB
Markdown
162 lines
3.0 KiB
Markdown
# 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
|
||
|
||
1. Preserve live behaviour
|
||
2. Prefer extraction over rewrite
|
||
3. Work in small, safe slices
|
||
4. Keep changes reversible
|
||
5. Protect:
|
||
- save/resume flows
|
||
- upload behaviour
|
||
- submission/finalisation
|
||
6. 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:
|
||
|
||
1. follow slice-based approach
|
||
2. implement one concern per slice
|
||
3. validate behaviour after each slice
|
||
4. merge into `refactor` only when safe
|
||
5. 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.
|