pedwfrontend/reports/crm-case-progress-display-assessment.md

CRM Case Progress Display – Planning Review Assessment

Active branch: feature/crm-case-progress-display-planning

Assessment scope: planning-only review of existing repository evidence to assess whether CRM Case Progress Display should become a formal investigation stream.

---

1. What has already been discovered?

Known facts

• CRM is the system of record for case progression and status; the portal consumes CRM state through relay-backed API queries rather than owning the operational progression itself.
• The portal already uses CRM-owned statuscode widely across public search, case summary, my portal, watched cases, admin dashboards, and lifecycle display.
• The portal also reads pinswg_casestage directly in case summary presentation, indicating that both stage-like and status-like CRM fields already influence the UI.
• The portal contains a read-only lifecycle interpretation seam in lib/domain/case-lifecycle, but that boundary explicitly does not claim ownership of lifecycle semantics, progress/status calculation ownership, dashboard behaviour, or closed-case handling.
• Lifecycle display is currently driven by stage catalogues keyed by appeal type and mapped from CRM-derived inputs, rather than by a single explicit business model.
• Dashboard/worklist grouping uses additional state concepts beyond CRM statuscode, including servicestage eq 1 for awaiting-submission cases and watched-case submission markers such as pinswg_representationsubmitted.

Known ownership boundaries

• CRM ownership: operational case status/progression data (statuscode, pinswg_casestage, related entity fields, formatted labels).
• Portal API ownership: fetch and lightly reshape CRM data for consumers; examples include getmycases_api, getawaitingsubmission_api, and getwatchedcases_api.
• Portal lifecycle seam ownership: read-only interpretation and lookup behaviour, not source semantics (lib/domain/case-lifecycle/README.md).
• Dashboard policy ownership: limited watched/submitted classification for watched cases only; not overall dashboard lifecycle meaning (lib/domain/dashboard-policy/README.md).
• Appeal-type policy ownership: family classification only, not lifecycle/status behaviour (lib/domain/appeal-type-policy/README.md).

Known consumer groups

• Public search results and case pages.
• Authenticated portal users in my portal panels and view-all screens.
• Watched-case and representation users.
• Admin/reporting views that aggregate counts by statuscode and appeal type/LPA.
• Case-summary users consuming the staged “status” journey view.

Known transformations

• Raw CRM statuscode is transformed into:
  • formatted public-facing status labels,
  • stage-journey progress via getLifecycleStagesForCase(...),
  • aggregated reporting buckets/counts in admin dashboards,
  • worklist segmentation such as awaiting submission, watched, and submitted representations.
• Specialist-process and appeal-type mappings influence which lifecycle stage catalogue is used.
• The portal reshapes watched-case and case query payloads by copying/renaming fields for UI convenience.
• Dashboard/worklist interpretations mix CRM data with portal-owned workflow markers such as blob-backed drafts and representation-submitted flags.

Conclusion: the repository already shows that this area is not a single raw CRM status display. It is a multi-consumer interpretation layer spanning operational status, staged progress presentation, workflow segmentation, and reporting aggregation.

---

2. What remains unknown?

The most important genuine unknowns are:

1. statuscode vs pinswg_casestage relationship

   • It remains unclear whether these represent parallel CRM concepts, a primary/secondary lifecycle pair, or historical overlap.

2. Lifecycle journey ownership

   • It is not yet clear whether the staged journey shown in case status is an intentional business-facing lifecycle model or a portal-side presentation mapping layered on top of CRM statuses.

3. Specialist-process influence on lifecycle display

   • Specialist process is already used to choose stage catalogues in some flows, but the intended ownership and completeness of that influence is unclear.

4. Closed-state and non-intuitive stage handling intent

   • The lifecycle seam explicitly preserves ambiguity around status vs stage and closed-case behaviour, which implies unresolved semantics.

5. Progress display consistency across consumers

   • Public search, case summary, my portal panels, watched cases, and admin dashboards all consume status differently; it is unclear which differences are deliberate versus incidental.

6. Reporting interpretation boundaries

   • Admin dashboards aggregate directly by statuscode, but it is unclear whether those counts represent operational CRM reporting only or are intended to align with user-facing lifecycle stages.

7. Portal workflow vs CRM lifecycle boundary

   • Drafts, awaiting submission, submission processing, and submitted representations already use portal and blob/worklist concepts. The precise boundary between CRM lifecycle and portal workflow state remains unclear.

8. Whether current stage catalogues encode business meaning or UI narrative only

   • The repository contains large appeal-type-specific stage arrays, but current evidence does not prove whether they are authoritative business semantics or user-guidance presentation.

---

3. Classification Assessment

This area should currently be classified as a mixture of multiple model types.

B. Presentation Model

Selected: Yes

Evidence

• components/case/status.js renders a staged progress UI from interpreted lifecycle stages.
• components/case/summary/utils/caseStagesByAppealType.js contains appeal-type-specific stage catalogues with title/description translation keys, which is strong evidence of a presentation-oriented journey model.
• The lifecycle boundary README explicitly says it is a read-only interpretation seam and does not define new lifecycle semantics.

C. CRM Compatibility Layer

Selected: Yes

Evidence

• docs/query-profile-compatibility.md states CRM field names are the source of truth and that downstream status/lifecycle views depend on preserving CRM field variants.
• The system preserves raw CRM statuscode and variant field shapes rather than normalizing them into a single clean internal model.
• API routes and search/case components depend on CRM formatted values and raw fields directly.

D. Reporting Model

Selected: Yes

Evidence

• Admin endpoints such as getStatusCountsByAppeal_api.js, getStatusCountsByAppealAndLPA_api.js, and getAppealsByStatusCounts_api.js aggregate counts by statuscode for dashboards and drill-down search links.
• This is a distinct consumer need from case-summary lifecycle presentation.

E. User Workflow Model

Selected: Yes

Evidence

• context/domain-flows.md documents portal-visible states such as awaiting submission, pending, and submission processing.
• getawaitingsubmission_api.js segments cases using servicestage eq 1, and dashboard policy separately classifies watched/submitted records using representation submission markers.
• These workflow concepts are not reducible to the case-summary lifecycle display alone.

A. Business Decision Model

Selected: Maybe / partial only

Evidence for limited inclusion

• The portal definitely makes repeatable interpretation decisions about which stage journey to show, which bucket a record belongs in, and which status label/count to expose.
• However, current repository evidence does not yet prove that this is a coherent, intentional business decision model in the same way representation participation was shown to be.
• Existing docs explicitly preserve ambiguity: the lifecycle seam says it does not own semantics and must preserve “status-vs-stage ambiguity”.

Assessment: this is not yet convincingly classifiable as a pure business decision model. It looks more like a presentation/compatibility/workflow/reporting mixture with some embedded business meaning.

---

4. Architectural Value Assessment

If further characterization were performed, the likely outputs would be:

1. Ownership map

   • Clarify which lifecycle/status meanings are owned by CRM versus interpreted by portal presentation, dashboard logic, and reporting.

2. Transformation map

   • Trace how raw CRM fields (statuscode, pinswg_casestage, specialist process, service stage, representation submission flags) become user-facing lifecycle stages, worklists, and reporting summaries.

3. Presentation model documentation

   • Document what the case-status journey actually represents per appeal type and whether it is intended as user guidance, operational translation, or formal lifecycle narrative.

4. Compatibility documentation

   • Record which CRM field dependencies and ambiguities are compatibility-sensitive and must be preserved.

5. Consumer divergence map

   • Identify where public search, case summary, my portal, watched cases, and admin dashboards intentionally diverge or accidentally drift.

6. Workflow boundary clarification

   • Separate CRM operational lifecycle from portal draft/submission/worklist state.

Likely value

The main value would be architectural clarity, not immediate extraction. It would reduce ambiguity for future refactor slices touching case summary, search, my portal, admin reporting, and CRM integration seams.

---

5. Domain Candidate Assessment

Answer: Maybe

Evidence

• There is already a narrow lib/domain/case-lifecycle seam, which indicates the codebase has identified this as a potentially separable interpretation concern.
• The area spans multiple consumers and repeated translation logic, which is a common signal of a future domain-layer candidate.
• However, the current seam explicitly avoids owning semantics, progress/status calculation ownership, dashboard behaviour, and closed-case handling.
• The evidence currently points to a mixed concern area rather than a stable, well-bounded domain policy.

Conclusion: this looks like a future domain-layer candidate only if characterization first clarifies ownership and semantics. Today it is too ambiguous and multi-purpose to treat as a clearly ready domain boundary.

---

6. Cost vs Value Assessment

Investigation Cost

Medium

Reasoning

• The evidence is already partially assembled through current docs and the extracted lifecycle seam.
• However, the concern spans many consumers: case summary, search, my portal, watched cases, admin dashboards, API queries, and stage catalogues.
• The ambiguity between status, stage, workflow, and reporting means a slice still requires careful cross-consumer characterization.

Architectural Value

High

Reasoning

• This area sits at a boundary between CRM integration, portal presentation, and user workflow interpretation.
• Clarifying it would improve future decision-making in several existing streams and reduce the risk of accidental semantic changes during refactor.
• The repository already names this as the next likely discovery candidate, which aligns with the observed ambiguity.

Maintenance Value

Medium to High

Reasoning

• Better understanding would help maintainers avoid conflating raw CRM status, lifecycle stage display, dashboard grouping, and workflow state.
• It would make future changes safer in high-touch files such as components/case/status.js, components/case/summary.js, components/myportal/viewall.js, and related API routes.
• Value is not yet “very high” because characterization alone would not immediately simplify the code unless followed later by carefully bounded extraction work.

---

7. Recommendation

Recommendation: Option B — Perform one characterization slice.

Supporting evidence

• Current understanding is not sufficient to say this is only CRM compatibility or only presentation.
• Existing evidence already proves this area mixes at least presentation, workflow, reporting, and compatibility concerns.
• A full characterization stream is not yet justified because representation participation business validation is still an active dependency in project context, and the scope here is broad.
• One bounded slice focused on ownership and transformation clarity would likely answer whether the broader stream is worthwhile.

Why not Option A:

• There are still material unknowns around statuscode vs pinswg_casestage, stage ownership, consumer divergence, and workflow/reporting boundaries.

Why not Option C:

• The current evidence supports further investigation, but not yet a full multi-slice stream without first proving that the ambiguity resolves into a coherent characterization target.

Why not Option D:

• This remains a stronger next investigation candidate than many other areas because the ambiguity is architectural, cross-cutting, and already partially surfaced by existing seams and docs.

---

8. Alternative Investigation Candidates

If CRM Case Progress Display is not taken next, the strongest evidenced alternatives from the repository are:

1. Portal workflow state / my portal worklist segmentation

   • Evidence: context/domain-flows.md, lib/domain/dashboard-policy/README.md, components/myportal/viewall.js, getawaitingsubmission_api.js, watched/submitted classification.
   • Why candidate: the portal already mixes draft, awaiting submission, watched, submitted, and representation states outside the lifecycle seam.

2. CRM integration boundary / status-query compatibility

   • Evidence: docs/query-profile-compatibility.md, actions/selectQueryTypes.js.
   • Why candidate: lifecycle and status views depend on CRM field selection and compatibility-preserving query shapes.

3. Submission journey state boundaries

   • Evidence: awaiting-submission blob flows, service-stage filters, draft continuation routes, and my portal segmentation.
   • Why candidate: this may produce a cleaner workflow-state understanding than starting with all lifecycle presentation concerns at once.

4. Notification / watched-case workflow interpretation

   • Evidence: getwatchedcases_api.js, dashboard-policy classification, watched vs submitted representation handling.
   • Why candidate: it exposes a narrower but related interpretation boundary between CRM case records and user-facing participation state.

These candidates are all evidenced in current repository state. None are invented.

---

9. Final Conclusion

Answer: B. Probably

Supporting evidence

• The codebase already shows this area is broader than simple CRM status display.
• There is clear evidence of multiple overlapping models: CRM operational status, staged case progress presentation, dashboard/worklist workflow grouping, and reporting aggregation.
• The existing lifecycle seam explicitly preserves ambiguity instead of resolving it, which suggests meaningful architectural understanding is still missing.
• However, the area does not yet show the same clear coherence as representation participation; therefore the likely value is real but should first be tested with one bounded characterization slice rather than a full stream.

Overall conclusion:

CRM Case Progress Display is likely to produce meaningful additional architectural understanding beyond what is already known, but only probably, not clearly enough yet to justify a full characterization stream immediately.

---

Assessment Outcome Summary

• Should this become a formal investigation stream now? Not yet as a full stream.
• Best next step: one bounded characterization slice.
• Current classification: mixed presentation + CRM compatibility + reporting + user workflow area, with partial business meaning but no proven single policy model yet.
• Domain-layer candidate assessment: Maybe.
• Cost/value: Medium investigation cost; High architectural value; Medium-to-High maintenance value.