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

# New Appeal Refactor — Current State of Play

## Purpose

This note updates the earlier **pre-refactor analysis** with the **current state after the Slice 1–8 refactor stream**.

Scope remains the new appeal flow areas:

- `pages/newappeal/**`
- `components/newappeal/**`

---

## Executive summary

The planned refactor stream has been completed through **Slice 8** on the `refactor` branch integration line.

- Behaviour-preserving objective has been maintained (S78 flow)
- Core journeys remained stable through regression checks
- Structural clarity has improved in the highest-risk areas
- The codebase is in a safer state for future controlled change

---

## Slice completion status (current)

All planned slices are complete:

1. Slice 1 — XML/Form derivation extraction ✅
2. Slice 2a — Payload cleanup helpers ✅
3. Slice 2b — File merge/dedupe helpers ✅
4. Slice 3 — Side-effect facade wrappers ✅
5. Slice 4 — BuildSection UI extraction ✅
6. Slice 5 — BuildCheckSection UI extraction ✅
7. Slice 6 — BuildCheckRow formatter-map cleanup ✅
8. Slice 7 — Nested prop-boundary simplification ✅
9. Slice 8 — Start flow readability cleanup (`createCase` / `aboutyou`) ✅

Tracker reference: `context/refactor-tracker.md`

---

## What changed overall

### Structural improvements delivered

- Repeated XML/form derivation logic moved into dedicated lib helpers
- Payload shaping and file-list merge/dedupe logic normalized into focused helpers
- Side effects wrapped behind clearer journey-effect boundaries
- Large UI-heavy files split with clearer presentational structure (Slices 4–5)
- Check-row formatting logic simplified into more maintainable mapping style
- Deep nested prop access reduced with local boundary aliases
- Start-flow components (`createCase`, `aboutyou`) made easier to read using local predicates/aliases

### What was intentionally preserved

- Business rules (including S78 behaviour)
- HASCAS mapping behaviour
- Appellant/agent branching behaviour
- Field names/IDs and payload shape
- Redirect/query construction (`lpa`, `apt`, `id`)
- Validation messages/rules
- Navigation and side-effect ordering/timing
- EN/CY parity

---

## Current architecture quality (post-stream)

### Stronger than before

- Better separation between derivation/formatting/helpers and component rendering
- Reduced duplication in payload/file processing paths
- Safer change surfaces in `buildsection`, `buildchecksection`, and start flow
- Improved readability of high-churn components

### Still sensitive / needs caution

- `buildsection.js` and `buildchecksection.js` remain central orchestration points
- Save/resume and submit/finalise paths still require strict regression discipline
- Some legacy patterns/comments remain and can obscure intent

---

## Risk position now

### Risks reduced

- Regression risk from duplicated transformation logic
- Coupling risk from deep nested prop traversal
- Reviewability risk in large mixed-concern components
- Formatting-logic drift risk in check-answers rendering

### Risks still present (manageable)

- Live-flow sensitivity for save/resume/upload/submit remains inherently high
- Manual regression burden is still significant for confidence
- Further cleanup must continue to avoid behaviour changes

---

## Deferred follow-up items (post-stream)

These are **not part of Slice 1–8** and should be handled as separate scoped work:

1. Add/expand targeted automated regression coverage for protected journeys
2. Remove stale/commented legacy code in touched components (safe cleanup slices)
3. Document critical invariants for save/resume/submit paths in a concise maintainer note
4. Continue incremental decomposition of remaining orchestration-heavy components only if behaviour can be proven unchanged

---

## Validation position

Regression evidence recorded across slices indicates preserved behaviour for:

- Start appeal and section navigation
- Save and exit
- Resume
- Upload and file handling
- Check answers rendering
- Submit/finalisation
- Confirmation/email paths
- EN/CY parity
- CRM insertion smoke
- Lint baseline (warnings-only, no new blocking errors)

---

## Conclusion

Compared to the earlier analysis, the new appeal flow is now in a materially safer and more maintainable state while preserving live behaviour.

The planned refactor stream (Slices 1–8) is complete. Any additional improvements should proceed as new, tightly scoped, behaviour-preserving slices.

---

## What should be done next

## 1) Stabilise and release safely (immediate)

Before any merge into `SIPS-Development`, run a formal readiness pass on `refactor`:

1. `npm run lint` (confirm no new blocking issues)
2. Full protected-journey manual regression:
    - start appeal
    - save and exit
    - resume
    - upload documents
    - check answers
    - submit
    - confirmation
3. EN/CY parity pass on touched paths
4. Negative-path checks on validation and conditional branches
5. CRM insertion smoke validation
6. Rollback verification (revert path by merge commit)

If any check fails, fix in a separate, minimal safety slice.

## 2) Close out stream documentation (short, high-signal)

Add a concise closeout note (or PR summary block) that captures:

- stream scope and completed slices
- behaviour-preservation statement
- validation evidence references
- known constraints that must not change in future work

Keep this short and avoid duplicating implementation detail.

## 3) Start a post-stream backlog (separate from Slice 1–8)

Create a small follow-up backlog of **new, independent slices** (do not reopen completed slices):

- automated regression coverage for protected journeys
- safe removal of stale commented/dead code
- targeted cleanup of remaining orchestration hotspots (`buildsection`, `buildchecksection`) only when backed by tests/regression checks
- brief maintainer notes for critical invariants (payload shape, route/query contract, side-effect ordering)

## 4) Recommended execution order for follow-ups

Safest sequence:

1. Release-readiness and merge safety checks
2. Regression automation improvements
3. Documentation/invariant notes
4. Small structural cleanups in high-risk files (one concern per slice)

## 5) Guardrails for all next work

Continue to enforce refactor-branch rules:

- no business-rule changes
- no payload/field-name/query-shape drift
- no side-effect timing/order changes unless explicitly scoped and proven safe
- preserve EN/CY parity
- keep slices small, reversible, and independently testable

---

## Potential improvements to logic and functionality (future work)

These items are intentionally listed as **future enhancements** (not part of completed refactor slices).

Any item that changes user-facing behaviour, business rules, or decision logic should be delivered as product-approved feature work with explicit regression protection.

## 1) Validation and data-quality improvements

- Strengthen cross-field validation where dependencies are currently implicit (for example, conditional requirements tied to prior answers).
- Introduce clearer, field-level validation feedback for complex text/rich-text inputs.
- Add stricter normalization for user-entered contact data (format quality, consistency) while preserving accepted legacy cases.

## 2) Save/resume robustness

- Add structured save/resume integrity checks to detect and recover from partial or stale payloads.
- Improve diagnostics around resume hydration mismatches (field missing, incompatible shape, stale section state).
- Add explicit handling for interrupted upload/save sequences to reduce user recovery friction.

## 3) Upload/document experience and safety

- Improve duplicate-document handling feedback (clear user messaging when dedupe occurs).
- Provide more explicit upload status and retry outcomes for failed or partial uploads.
- Add stronger document-type validation messaging and edge-case handling for borderline file metadata.

## 4) Submit/finalisation resilience

- Add clearer user-safe fallback states for finalisation failures (e.g., PDF generation or downstream completion messaging failures).
- Improve idempotency safeguards in final submission steps to reduce accidental duplicate side effects.
- Strengthen auditability of submit transitions for operational support/debugging.

## 5) Start-flow usability enhancements

- Improve guidance for appeal-type selection and conditional HASCAS confirmation to reduce user error.
- Consider smarter defaults/prefill where policy allows, especially for known user profile/contact fields.
- Improve branch-specific helper copy for appellant vs agent pathways.

## 6) Performance and maintainability improvements

- Reduce repeated in-component derivation cost by introducing safe memoization where values are stable.
- Continue incremental decomposition of remaining orchestration-heavy components into testable units.
- Expand targeted automated tests (journey-level + high-risk utility-level) to lower regression burden.

## 7) Recommended delivery model for these improvements

- Treat each enhancement area as a separate, tightly scoped slice.
- Prioritise by user risk and operational impact:
    1. save/resume robustness
    2. submit/finalisation resilience
    3. validation/data-quality improvements
    4. upload/document UX resilience
    5. usability/performance refinements

- For each slice, require:
    - explicit statement of intended behaviour change (or confirmation of no change)
    - EN/CY parity checks
    - negative-path checks
    - rollback plan

---

## Evolving this into a multi-appeal-type platform (beyond S78)

To move from an S78-focused journey to a reusable **new appeal platform**, the safest path is to keep S78 as the baseline contract and introduce platform capabilities in additive slices.

## Platform principles

- Keep **S78 as reference behaviour** (do not regress)
- Drive variation via **configuration and schema**, not hardcoded branching
- Keep a stable core runtime for:
    - start/resume/save
    - section rendering
    - validation execution
    - upload/check/submit/finalise
- Isolate appeal-type specifics behind explicit adapters

## Recommended platform workstreams

## 1) Appeal-type definition contract

Define a typed “appeal definition” model for each appeal type, covering:

- metadata (id, route key, labels, EN/CY text references)
- section order and visibility rules
- field/validation rules
- required-doc rules
- submission/finalisation behaviour flags

Start by expressing S78 in this contract first, then add new appeal types using the same contract.

## 2) Start-flow strategy model

Generalise `createCase`/`aboutyou` into a strategy-driven start flow:

- shared start-flow shell
- per-appeal-type start-step configuration
- clear branching policy hooks (e.g., HASCAS-style gates as config)

This avoids adding new hardcoded conditions per appeal type.

## 3) Validation engine boundary

Move towards a validation layer that consumes appeal-definition rules:

- common validator primitives
- per-appeal rule sets loaded by appeal type
- explicit cross-field dependency maps

Preserve existing messages/behaviour for S78 while introducing extension points.

## 4) Section and field rendering registry

Introduce a registry pattern for section/field rendering rules:

- field-type renderer map (already partially established)
- appeal-type-specific section decorators where needed
- strict fallback behaviour for unsupported fields

This enables incremental onboarding of new forms without rewriting core flow components.

## 5) Submission and integration adapters

Define adapter interfaces for variation points:

- payload mapping by appeal type
- finalisation actions by appeal type
- notification templates by appeal type/locale

Core workflow should call adapters, not branch inline by appeal type.

## 6) Platform test matrix and release gates

Adopt a matrix-driven regression model:

- rows: appeal types
- columns: protected journeys + EN/CY parity + negative paths

Require S78 baseline pass + new-type pass before release.

## Suggested delivery sequence (safe)

1. Define appeal-type contract (S78 only)
2. Map current S78 start flow to strategy model (no behaviour change)
3. Introduce validation/section registries behind existing behaviour
4. Add adapter boundaries for submit/finalise integrations
5. Pilot one additional appeal type behind feature flag/config gating
6. Expand matrix automation and observability

## Guardrails while platformising

- Do not change S78 business behaviour unintentionally
- No payload/field/query contract drift for existing types
- Preserve save/resume compatibility
- Preserve EN/CY parity across all onboarded types
- Keep rollout incremental with clear rollback per slice