## 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.