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.