# 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.