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