Merged PR 2435: Add workflow orchestration documentation validation
Add workflow orchestration documentation validation Related work items: #23754
This commit is contained in:
Robert Bond
@@ -0,0 +1,290 @@
|
||||
# Workflow / Orchestration Documentation Validation
|
||||
|
||||
## Purpose
|
||||
|
||||
Validate whether PEDW's existing architecture documentation already contains enough information to describe the workflow/orchestration model, without reopening broad workflow discovery or performing route-by-route API analysis.
|
||||
|
||||
This is a documentation-validation and consolidation slice only.
|
||||
|
||||
## Required Context Read
|
||||
|
||||
The following files were read before this validation was drafted:
|
||||
|
||||
- `context/architecture.md`
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/api-grouping-workflow-boundary-assessment.md`
|
||||
- `context/api-grouping-adoption-roadmap.md`
|
||||
- `context/portal-api-platform-assessment.md`
|
||||
- `context/integration-map.md`
|
||||
- `memory-bank/change-log.md`
|
||||
- `memory-bank/open-questions.md`
|
||||
|
||||
Confirmed: all required context above was read.
|
||||
|
||||
## Validation Summary
|
||||
|
||||
### Validation question
|
||||
|
||||
Do the existing PEDW architecture documents already contain enough information to describe the workflow/orchestration model?
|
||||
|
||||
### Short answer
|
||||
|
||||
**Yes — with minor caveats.**
|
||||
|
||||
The current documentation set is already sufficient to describe PEDW's workflow/orchestration model at an architecture and maintainer-guidance level for the core areas requested here.
|
||||
|
||||
The strongest evidence already exists in:
|
||||
|
||||
- `context/journey-architecture-map.md`
|
||||
- explicit draft-appeal lifecycle map
|
||||
- explicit appeal submission/finalisation map
|
||||
- explicit draft-representation lifecycle map
|
||||
- explicit representation submission/finalisation map
|
||||
- explicit ownership transitions, queue handoff, CRM transition boundary, completion-state handling, PDF generation, and Notify/email side effects
|
||||
- `context/api-route-map.md`
|
||||
- journey-owned route families and integration boundaries for draft and finalisation areas
|
||||
- `context/api-grouping-workflow-boundary-assessment.md`
|
||||
- explicit classification of appeals and representations as workflow/orchestration boundaries
|
||||
- `context/architecture.md`
|
||||
- stable platform-level route-family and ownership model, including storage, queue/finalisation, notification orchestration, and upstream ownership propagation
|
||||
- `context/integration-map.md`
|
||||
- platform-level integration responsibilities for CRM, Notify, Azure Storage/Queues, and PDF generation
|
||||
|
||||
What is **not** fully documented is downstream processing beyond the explicit frontend-visible queue handoff / CRM transition boundary. However, that gap does **not** prevent the current architecture set from already describing the visible PEDW workflow/orchestration model.
|
||||
|
||||
## Existing Evidence Map
|
||||
|
||||
### 1. Draft appeal lifecycle
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/architecture.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- Draft appeal creation is documented as a storage-owned lifecycle.
|
||||
- Ownership root is explicitly described as `NextAuth session.user.id -> container identity -> Azure Storage container`.
|
||||
- Draft save, resume, file upload, progress blob state, and awaiting-submission context are already mapped.
|
||||
- Principal pages, loaders, Redux owners, services, file routes, and integration boundaries are already identified.
|
||||
- **Remaining gap, if any:**
|
||||
- No major architecture gap for describing the visible draft lifecycle.
|
||||
|
||||
### 2. Appeal submission / finalisation
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/api-grouping-workflow-boundary-assessment.md`
|
||||
- `context/architecture.md`
|
||||
- `context/integration-map.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- Submission is explicitly documented as an orchestration-owned transition.
|
||||
- The journey map already records the visible sequence through check answers, PDF generation, completion-message route, Azure Queue creation, and CRM mutation boundary.
|
||||
- Principal orchestration and CRM mutation routes are identified.
|
||||
- Completion-state handling (`setCurrentSection(9999)` / completion UI boundary) is already documented.
|
||||
- Queue handoff and storage-to-CRM ownership transition are already called out explicitly.
|
||||
- **Remaining gap, if any:**
|
||||
- Downstream queue consumer behaviour outside this repository remains out of scope, but the visible orchestration model is already documented sufficiently.
|
||||
|
||||
### 3. Draft representation lifecycle
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/architecture.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- Draft representation lifecycle is already documented as storage-backed and container-owned.
|
||||
- Ownership is explicitly described as `session.user.id -> containerID -> Azure Storage container -> rep draft JSON / representation file subtree`.
|
||||
- The journey map already captures case-linked draft identity, `repfile_name`, draft resume, file retrieval, and representation-specific state ownership.
|
||||
- Relevant pages, loaders, routes, services, and integration boundaries are already mapped.
|
||||
- **Remaining gap, if any:**
|
||||
- No major architecture gap for describing the visible draft representation lifecycle.
|
||||
|
||||
### 4. Representation submission / finalisation
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/api-grouping-workflow-boundary-assessment.md`
|
||||
- `context/architecture.md`
|
||||
- `context/integration-map.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- Representation finalisation is already documented as a workflow/orchestration boundary.
|
||||
- The journey map already records involvement creation, representation completion message creation, Azure Queue handoff, Notify/email send, and watched/submitted side effects.
|
||||
- The distinction from appeal finalisation is already explained.
|
||||
- Relevant routes, state owners, services, and integrations are already identified.
|
||||
- **Remaining gap, if any:**
|
||||
- Downstream queue processing beyond the handoff remains outside visible repository scope, but the architecture-level orchestration model is already sufficiently documented.
|
||||
|
||||
### 5. Azure Storage ownership
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/architecture.md`
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-grouping-adoption-roadmap.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- `context/architecture.md` states that storage ownership is rooted in `session.user.id`.
|
||||
- The journey map makes this concrete for both appeal and representation drafts.
|
||||
- The adoption roadmap preserves Azure Storage ownership boundaries for draft-owned content as an architecture principle.
|
||||
- **Remaining gap, if any:**
|
||||
- None needed for architecture-level workflow description.
|
||||
|
||||
### 6. Queue handoff
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/integration-map.md`
|
||||
- `context/remaining-architecture-candidates.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- Appeal and representation completion routes are both explicitly documented as queue/finalisation boundaries.
|
||||
- The appeal lifecycle already records the queue payload carrying storage artifact paths.
|
||||
- The representation lifecycle already records the explicit completion-message route and queue handoff.
|
||||
- Integration-map coverage confirms Azure Storage + Queues as a core platform boundary.
|
||||
- **Remaining gap, if any:**
|
||||
- Queue consumer implementation downstream is not documented here, but the handoff boundary itself is already adequately documented.
|
||||
|
||||
### 7. CRM transition boundary
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/architecture.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- The appeal journey map explicitly describes the transition from storage-owned draft state toward CRM-backed submitted records.
|
||||
- The representation journey map explicitly describes the CRM involvement / representation boundary after queue handoff.
|
||||
- `context/architecture.md` already distinguishes storage ownership from CRM contact ownership.
|
||||
- **Remaining gap, if any:**
|
||||
- Exact downstream CRM-processing implementation remains outside this documentation slice, but the transition boundary itself is already explicit enough.
|
||||
|
||||
### 8. PDF/document generation where relevant
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/integration-map.md`
|
||||
- `context/architecture.md`
|
||||
- **Coverage level:** **Partially sufficient**
|
||||
- **What is already known:**
|
||||
- Appeal submission documentation explicitly includes PDF generation in the visible finalisation sequence.
|
||||
- Representation flows already identify `generateRepPDF(...)` where applicable.
|
||||
- Integration-map and architecture docs identify the PDF/document generation integration boundary and primary files.
|
||||
- **Remaining gap, if any:**
|
||||
- Existing docs are sufficient to place PDF generation in the workflow, but less detailed on representation-specific PDF decision points and exact document-generation sequencing nuances than for appeals.
|
||||
|
||||
### 9. Notify/email side effects where relevant
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/architecture.md`
|
||||
- `context/integration-map.md`
|
||||
- `context/api-grouping-workflow-boundary-assessment.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- Completion emails for appeals and representations are already documented in the journey map.
|
||||
- Sign-in email and notification orchestration are already documented separately in the auth/email slice.
|
||||
- Notify is already documented as both an auth-support integration and a business-notification integration.
|
||||
- The notification/orchestration distinction is already explicit in the workflow-boundary assessment.
|
||||
- **Remaining gap, if any:**
|
||||
- None significant for architecture-level workflow documentation.
|
||||
|
||||
### 10. Completion-state handling
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- Appeal completion-state handling is explicitly documented through `currentSection = 9999` and `CompleteAppeal` UI transition.
|
||||
- Representation completion-state flags such as `representationSubmit`, `representationSubmitConfirmation`, and `representationMessageSent` are already identified.
|
||||
- The distinction between visible UI completion and true backend handoff/completion is already documented.
|
||||
- **Remaining gap, if any:**
|
||||
- None significant for the requested validation question.
|
||||
|
||||
### 11. Integration sequencing
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/architecture.md`
|
||||
- `context/integration-map.md`
|
||||
- `context/api-grouping-workflow-boundary-assessment.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- The journey map already documents ordered workflow sequences for both appeal and representation finalisation.
|
||||
- Platform docs already classify these areas as orchestration-heavy and cross-integration.
|
||||
- Integration-map identifies the integrations involved and their roles.
|
||||
- **Remaining gap, if any:**
|
||||
- No major gap for an architecture-level model; only downstream operational sequencing beyond queue handoff remains outside scope.
|
||||
|
||||
### 12. Ownership transitions
|
||||
|
||||
- **Existing document(s):**
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/architecture.md`
|
||||
- `context/api-grouping-adoption-roadmap.md`
|
||||
- **Coverage level:** **Sufficient**
|
||||
- **What is already known:**
|
||||
- Storage-owned draft state and CRM-owned submitted state are already explicitly contrasted.
|
||||
- Appeal ownership transition is already documented from container-scoped draft ownership to queue handoff to CRM submitted-record boundary.
|
||||
- Representation ownership transition is already documented from draft ownership to queue handoff to CRM involvement / representation boundary.
|
||||
- Platform docs reinforce the split between storage ownership and CRM ownership.
|
||||
- **Remaining gap, if any:**
|
||||
- None significant for the requested documentation-validation purpose.
|
||||
|
||||
## Overall Assessment
|
||||
|
||||
The existing PEDW architecture materials **already contain enough information to describe the workflow/orchestration model** for the requested workflow areas.
|
||||
|
||||
Most importantly, PEDW does **not** currently have a documentation gap so large that another broad workflow/orchestration discovery stream is justified.
|
||||
|
||||
The documentation set already provides:
|
||||
|
||||
- explicit draft lifecycle descriptions for appeals and representations
|
||||
- explicit submission/finalisation lifecycle descriptions for appeals and representations
|
||||
- explicit storage ownership roots
|
||||
- explicit queue handoff boundaries
|
||||
- explicit CRM transition boundaries
|
||||
- explicit completion-state handling
|
||||
- explicit integration sequencing at architecture level
|
||||
- explicit Notify/email side effects where relevant
|
||||
- explicit classification of these areas as workflow/orchestration-heavy boundaries
|
||||
|
||||
The remaining limitations are narrow and mostly concern:
|
||||
|
||||
- downstream queue consumer behaviour outside this repository
|
||||
- some PDF-generation detail being lighter than the rest of the workflow narrative
|
||||
|
||||
Those are **targeted depth gaps**, not evidence of missing broad workflow documentation.
|
||||
|
||||
## Recommendation
|
||||
|
||||
### Recommended next step
|
||||
|
||||
**small documentation consolidation only**
|
||||
|
||||
### Why
|
||||
|
||||
- The required workflow/orchestration model is already present across existing architecture materials.
|
||||
- The main opportunity is improved consolidation/findability, not another discovery pass.
|
||||
- A full workflow discovery stream would likely duplicate work already completed in `context/journey-architecture-map.md`, `context/api-route-map.md`, `context/api-grouping-workflow-boundary-assessment.md`, and `context/architecture.md`.
|
||||
|
||||
### New workflow/orchestration discovery justified?
|
||||
|
||||
**No — not at this time.**
|
||||
|
||||
If future work is needed, it should be limited to one of the following small follow-ups only:
|
||||
|
||||
1. clarify or cross-link PDF-generation coverage where representation-specific sequencing needs slightly more explicit wording
|
||||
2. improve cross-references between the journey map and the workflow-boundary assessment
|
||||
3. only perform targeted code validation later if a specific contradiction appears in existing docs
|
||||
|
||||
### Final recommendation choice
|
||||
|
||||
**small documentation consolidation only**
|
||||
@@ -18,6 +18,65 @@ Follow-ups:
|
||||
|
||||
---
|
||||
|
||||
### CL-2026-06-25-WORKFLOW-ORCHESTRATION-DOC-VALIDATION: validate whether existing architecture docs already cover PEDW workflow/orchestration
|
||||
|
||||
date: 2026-06-25
|
||||
author: Cline
|
||||
scope: `context/workflow-orchestration-documentation-validation.md`, `memory-bank/change-log.md`
|
||||
type: change
|
||||
rationale: Validate, using existing architecture documentation first, whether PEDW's workflow/orchestration model is already sufficiently documented for appeals and representations without reopening broad workflow discovery or performing route-by-route API review.
|
||||
impact: Documentation/context only; confirms current workflow/orchestration coverage across draft lifecycle, submission/finalisation, storage ownership, queue handoff, CRM transition, PDF/document generation, Notify/email side effects, completion-state handling, integration sequencing, and ownership transitions. No runtime, API, auth/session, CRM, storage, queue, notification, i18n, or behaviour change.
|
||||
status: completed
|
||||
|
||||
Summary:
|
||||
|
||||
- Confirmed the required context was read before validation:
|
||||
- `context/architecture.md`
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/api-grouping-workflow-boundary-assessment.md`
|
||||
- `context/api-grouping-adoption-roadmap.md`
|
||||
- `context/portal-api-platform-assessment.md`
|
||||
- `context/integration-map.md`
|
||||
- `memory-bank/change-log.md`
|
||||
- `memory-bank/open-questions.md`
|
||||
- Created new validation document:
|
||||
- `context/workflow-orchestration-documentation-validation.md`
|
||||
- Reused existing documentation as the evidence base and did not perform a new workflow discovery stream.
|
||||
- Validated the following workflow areas:
|
||||
- draft appeal lifecycle
|
||||
- appeal submission / finalisation
|
||||
- draft representation lifecycle
|
||||
- representation submission / finalisation
|
||||
- Azure Storage ownership
|
||||
- queue handoff
|
||||
- CRM transition boundary
|
||||
- PDF/document generation where relevant
|
||||
- Notify/email side effects where relevant
|
||||
- completion-state handling
|
||||
- integration sequencing
|
||||
- ownership transitions
|
||||
- Main conclusion:
|
||||
- existing PEDW architecture documents are already sufficient to describe the workflow/orchestration model at architecture level
|
||||
- strongest evidence is already present in `context/journey-architecture-map.md`, supported by `context/api-route-map.md`, `context/api-grouping-workflow-boundary-assessment.md`, `context/architecture.md`, and `context/integration-map.md`
|
||||
- the only notable gap is limited downstream detail beyond the visible queue handoff / CRM transition boundary, which does not justify another broad workflow discovery stream
|
||||
- Final recommendation recorded in the validation document:
|
||||
- **small documentation consolidation only**
|
||||
- no new workflow discovery needed at this time
|
||||
|
||||
Validation:
|
||||
|
||||
- Documentation-only validation.
|
||||
- Existing documentation used as primary evidence.
|
||||
- No route inventory, broad code discovery, implementation, migration, or refactor performed.
|
||||
- Intended lightweight validation for this slice:
|
||||
- `git diff --check`
|
||||
|
||||
Follow-ups:
|
||||
|
||||
- Prefer small documentation consolidation/cross-linking only if follow-up work is requested.
|
||||
- Do not open a new broad workflow/orchestration discovery stream unless a specific contradiction or missing boundary emerges.
|
||||
|
||||
### CL-2026-06-25-API-GROUPING-FACADE-SEARCH-VERTICAL-SLICE: active public search results grouping and service adoption
|
||||
|
||||
### CL-2026-06-25-API-GROUPING-WORKFLOW-BOUNDARY-ASSESSMENT: classify where the additive façade pattern should stop
|
||||
|
||||
Reference in New Issue
Block a user