# Representations Refactor — Current State of Play

## Purpose

This document captures the **pre-refactor state** of the representations flow and defines the starting point for the behaviour-preserving refactor stream.

It mirrors the approach used for the new appeal refactor and will be updated as slices are completed.

---

## Executive Summary

The representations flow is:

- functionally complete and live
- behaviourally stable
- structurally complex and tightly coupled

The flow currently:

- spans multiple entry points
- mixes UI, workflow, and data logic
- contains duplicated branching and rendering logic
- relies heavily on shared global state (`currentView`, `searchResultsObj`)

---

## Journey Overview

The user journey is:

1. Navigate to case summary page
2. Click **Make representation / consultation**
3. Enter representation flow
4. Select capacity
5. Select representation type
6. Enter content and upload files
7. Review check answers
8. Submit representation
9. View confirmation/completion

---

## Entry Points

### Primary Entry

- `CaseSummary` component
- CTA button logic determines:
    - whether representation is allowed
    - which label to display
    - which route to navigate to

### Route

- `/myportal/representation?case=<caseRef>`

---

## Dual Mode Behaviour (Critical)

The flow operates in two modes:

### 1. New Representation (from search/case)

- triggered from case summary CTA
- loads case data via search + details APIs
- initializes new representation state

---

### 2. Existing Representation (resume/edit)

- triggered via query param (`state`)
- loads representation from blob storage
- hydrates existing data and files

---

This dual-mode behaviour is a **major complexity driver**.

---

## Architecture Overview

### High-Level Structure

- Page layer (SSR + Redux hydration)
- Case component (core orchestration)
- Representation flow components (capacity/type/content/check)
- Shared helpers (`representationElements`)
- Service layer (case data, blob storage, CRM integration)

---

### Key Components

- `CaseSummary` → entry + CTA logic
- `Case` → main orchestration component
- Representation flow components:
    - capacity selection
    - representation type selection
    - content entry
    - check answers
    - completion

---

### State Management

Primary state dependencies:

- `currentView`
- `searchResultsObj`
- `myRepresentations`
- `filesForRepresentations`

Heavy reliance on deeply nested props.

---

## Current Architecture Issues

### 1. High Coupling

- UI, workflow logic, and data fetching are tightly mixed
- large components handle multiple responsibilities

---

### 2. Deep Prop Chains

Examples:

- `props.currentView.caseReference.*`
- `props.searchResultsObj.*`

This reduces readability and increases fragility.

---

### 3. Duplicated Logic

- appeal-type branching repeated across components
- summary rendering duplicated by case type
- representation form structure repeated across capacity types

---

### 4. Dual Entry Complexity

- separate logic paths for new vs existing representation
- mixed within the same components

---

### 5. Async Data Complexity

- chained service calls:
    - `getCase`
    - `getPortalModuleDetails`
- repeated across different contexts
- hard to reason about and test

---

### 6. Inline Business Logic

- eligibility rules embedded in UI components
- date checks and appeal-type logic duplicated
- LPA-specific behaviour scattered

---

## Risk Areas

High-risk areas that require extra caution:

- CaseSummary eligibility logic
- SSR/data-loading logic for representation page
- submission/finalisation flow
- file upload handling
- dual-mode entry (new vs existing)
- Redux hydration and state consistency

---

## Behavioural Constraints (Must Not Change)

- eligibility rules for making a representation
- journey step order and navigation
- validation rules and messaging
- payload structure sent to backend/CRM
- file upload and metadata behaviour
- submission/finalisation behaviour
- confirmation page behaviour
- route/query parameter structure
- EN/CY parity

---

## Comparison to New Appeal Flow

### Similarities

- step-based user journey
- check answers before submission
- file upload and validation steps
- finalisation/confirmation stage

---

### Differences (Important)

- dual-mode entry (new vs existing)
- more reliance on external data sources
- less structured “engine” (more implicit logic)
- heavier coupling to case summary and search flows

---

## Refactor Readiness

The flow is suitable for refactor because:

- behaviour is stable
- clear boundaries can be identified
- repeated patterns exist
- appeal refactor provides a proven model

---

## Refactor Strategy

The refactor will follow a **slice-based, behaviour-preserving approach**:

1. Extract entry logic (CaseSummary)
2. Separate SSR/data-loading concerns
3. isolate step resolution logic
4. decompose large components
5. clean up shared helpers
6. stabilize async/service layers
7. isolate submission/finalisation

---

## Initial Slice Focus

### Slice R1 — Entry Logic Extraction

Target:

- representation eligibility logic in `CaseSummary`

Goal:

- reduce coupling
- isolate decision logic
- prepare for safe downstream refactor

---

## Validation Position

At start of refactor:

- behaviour is assumed correct
- no structural isolation exists
- regression testing is manual

Each slice must:

- prove behaviour unchanged
- reduce complexity incrementally

---

## Conclusion

The representations flow is:

- behaviourally stable
- structurally complex
- suitable for controlled refactor

The goal is to:

- reduce coupling
- improve clarity
- enable safer future changes

without altering live behaviour.

---

## Next Step

Begin **Slice R1 — Representation Entry Logic Extraction**

Following strict guardrails and regression validation.