pedwfrontend/context/representations-refactor-current-state.md

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.