pedwfrontend/memory-bank/refactor-backlog.md

Refactor Backlog (Maintainability + System Integrity)

Last updated: 2026-03-12

Priority 1 — Split actions/index.js by concern

• Problem: Single high-coupling module mixes API clients, hash/token helpers, logging, file/email/domain operations.
• Why it matters: Hard to reason about changes; high regression risk from unrelated edits.
• Target outcome: Small modules with explicit boundaries (e.g. relayClient, fileClient, notifyClient, caseService, authService).
• Initial scope: create façade layer first, then migrate call sites incrementally.
• Detailed plan: memory-bank/refactor-plan-actions-index.md
• Test gate: add unit regression tests + coverage reporting as part of this refactor.

Priority 2 — Centralize relay/hash/token forwarding logic

• Problem: pages/api/endpoint/** and related routes duplicate request-signing + token + forwarding behavior.
• Why it matters: Security-sensitive drift and inconsistent error handling.
• Target outcome: Shared relay utility enforcing one signing contract, one timeout/retry policy, one error map, one redacted logging strategy.
• Initial scope: pilot on a small endpoint group, then roll out pattern.

Priority 3 — Extract breadcrumb/back-link route-state rules

• Problem: Navigation logic in components/breadcrumbs.js and case summary is branch-heavy and query-dependent.
• Why it matters: Frequent regressions in search -> case -> myportal paths.
• Target outcome: Pure route-state helpers with table-driven tests; UI component mainly renders output.
• Initial scope: isolate va/adv/ads/key decision matrix first.

Priority 4 — Standardize security guards in pages/api/file/**

• Problem: Hash/guard enforcement appears inconsistent across file endpoints.
• Why it matters: Uneven protection for document upload/download/delete paths.
• Target outcome: Shared guard middleware for hash/auth/input validation + consistent negative-path responses.
• Initial scope: enforce a common pre-handler contract on high-risk routes first.

Priority 4 — Current slice status (2026-03-23)

• Completed on TASK22224-file-endpoint-contract-bundle:
  • pages/api/file/downloadblob.js hardening + hotfix closure
  • path normalization compatibility (filename-only + prefixed path)
  • encoded/raw hash validation compatibility guard
• Confirmed outcome:
  • user-reported download failures resolved
  • phase21 file + combined contract suites passing

Priority 4 — Next recommended slice on this branch

• Target routes:
  • pages/api/file/deleteblob.js
  • pages/api/file/deleteblobcase.js
  • pages/api/file/deleteblobrep.js
• Scope:
  • align hash canonicalization strategy with downloadblob.js
  • enforce explicit respondError contracts (MISSING_REQUIRED_QUERY, INVALID_HASH, route-specific *_FAILED)
  • preserve existing success payload shapes
  • extend tests/phase21/file-handler-contract.test.cjs with mixed encoded/raw hash variants and negative paths

Priority 5 — Establish minimum automated regression baseline

• Problem: Limited automated tests for high-risk logic.
• Why it matters: Repeated regressions and heavy manual verification burden.
• Target outcome: Focused test suite for pure logic and high-risk decisions.
• Initial scope:
  1. breadcrumb decision matrix
  2. representation eligibility/date windows
  3. hash utility behavior
  4. locale rewrite mapping sanity checks

Priority 6 — Decompose components/elements/index.js monolith (phased)

• Problem: components/elements/index.js has grown into a high-coupling UI monolith (~2700+ LOC) combining field primitives, validation/conditional logic, translation helpers, file-upload orchestration, and field-array behavior.
• Why it matters: Very high regression surface for new appeal/my portal forms, slower change velocity, and poor testability/isolation.
• Target outcome: components/elements/index.js reduced to a thin barrel export with responsibility split into focused modules.
• Context alignment: Matches architecture direction in context/architecture.md (endpoint/component sprawl reduction, bounded slices) and file boundary guidance in context/coding-conventions.md (pages thin, reusable logic/components split by concern).
• Guardrail constraints:
  • Preserve public-service reliability for core flows (search, case, myportal, newappeal).
  • No auth/session/security header behavior changes (out of scope).
  • Maintain EN/CY parity for user-facing behavior.
  • Keep accessibility behavior unchanged (labels, focus, keyboard flow, errors).

Priority 6 — Phase 1 (start here): extract pure helpers only

• Scope (Phase 1 only):

  • Move pure/helper logic from components/elements/index.js into focused helper modules under components/elements/ (or components/elements/helpers/) without behavior change.
  • Candidate helper extraction set:
    • translation helpers (FieldsTranslations, picklist translation helper)
    • file upload helper utilities (icon/doc type naming/pure format helpers)
    • other deterministic pure functions used by field renderers
  • Keep all field renderers/components in place for Phase 1.

• Non-goals (Phase 1):

  • No JSX component relocation yet.
  • No upload flow logic rewrites.
  • No validation rule behavior changes.
  • No prop contract changes for existing consumers.

• Acceptance criteria (Phase 1):

  • components/elements/index.js imports extracted helpers from new helper modules and behavior remains equivalent.
  • No route/API changes.
  • Existing new appeal + myportal form journeys continue to function in EN and CY.
  • Accessibility smoke unchanged for touched form controls (label association, keyboard reachability, inline error visibility).
  • Lint passes for touched files.

• Validation matrix (minimum):

  1. npm run lint
  2. Manual smoke:
     • new appeal form step rendering + validation messages
     • myportal representation/new appeal editing flow controls
     • file upload field icon/name behavior unchanged
  3. Locale parity checks (EN/CY) for touched user-facing labels/routes.
  4. A11y smoke checks on touched fields (focus, labels, errors).

• Rollback plan (Phase 1):

  • Revert helper module extraction commit(s) to restore single-file implementation.
  • No migration/data rollback required.

• Next phases (for tracking):

  • Phase 2: extract low-risk leaf field renderer components.
  • Phase 3: extract RenderFileUpload and upload container.
  • Phase 4: extract field-array/repeater components.
  • Phase 5: finalize components/elements/index.js as barrel-only export.

Sequencing recommendation

1. Priorities 2 + 4 (security/integrity foundation)
2. Priority 3 (high-change regression hotspot)
3. Priority 1 (structural maintainability)
4. Priority 5 (continuous safety net, starts early and expands)