pedwfrontend/context/refactor-branch-charter.md

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.