pedwfrontend/context/workflow-orchestration-documentation-validation.md

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