Workflow — Frontend blueprint¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
| Workflow id | frontend-blueprint · version 1 · Draft (Draft → InReview → Published → Deprecated, BC-04) |
| Coordinator | frontend-blueprint-coordinator · family Blueprint & Microservice Assembly |
| Owner service | WorkflowEngineService (BC-38) under Run Control (BC-03) |
| Starts on | readiness bundle readiness-bundle-v1 → RunAccepted from RunControlService when payload.workflowId == 'frontend-blueprint' (event) |
| Steps | 5 · gated 0 · agents 1 |
| Budget per run | 600000 tokens · cap 60.0 USD · 240 min |
| Descriptor | workflow-definition-v1 · schema |
| Status | target |
Builds the Frontend Blueprint from the Service and UX Blueprints: the shell, the microfrontends per work area, routes, state families, locales and the API bindings; validated against the DSL. It runs only for a product whose UX Blueprint exists.
Authored design, Draft (D54, D57)
These definitions were authored from the coordinator cards as design assumptions. None is published, evaluated or has run; agents are named by id as design bindings, not as tested integrations.
Activation (readiness bundle)¶
The Workflow Engine's readiness correlation (BC-38, ADR-0026) joins the signals below per project and bundle fingerprint and submits one run through Run Control's SubmitRun; the run then starts on RunAccepted like every other definition. Nothing starts on a raw event.
| Slot | Kind | Descriptor | Required | Satisfied by | Predicate |
|---|---|---|---|---|---|
service-blueprint |
blueprint (Service) | blueprint-service-v1 |
yes | BlueprintService.BlueprintValidated |
payload.kind == 'Service' and payload.passed == true |
ux-blueprint |
blueprint (Ux) | blueprint-ux-v1 |
yes | BlueprintService.BlueprintValidated |
payload.kind == 'Ux' and payload.passed == true |
- Consistency: members are satisfied only within the trusted tenant and project of the signal; a newer version of any member opens a new correlation and supersedes the open one
- Fingerprint: sha256 over the sorted list of slot
version:hash of every satisfied required and optional member
- Idempotency key:
{scope}:{operation}:{workflowReleaseId}:{bundleFingerprint} - Deduplication: the same key returns the existing run (SubmitRun: same Idempotency-Key, same canonical body); a new member version yields a new fingerprint and a new correlation, and the Open one is Superseded; a different body under the same key is a 409 and the correlation is Superseded with reason conflict
- Submit: workflow
frontend-blueprint(release aliaslatest), model profilecode-agent-strong, inputreadiness-bundle-v1, client referencecorrelationId.
Definition¶
flowchart TD
start(("RunAccepted"))
derive_composition["Derive the shell and microfrontends"]
draft_frontend_blueprint["Draft the Frontend Blueprint"]
submit_version[["tool: Submit the Draft version"]]
validate[["tool: Validate the blueprint"]]
check_valid{"Validation passed?"}
start --> derive_composition
derive_composition --> draft_frontend_blueprint
draft_frontend_blueprint --> submit_version
submit_version --> validate
validate --> check_valid
done(("WorkflowRunCompleted"))
check_valid --> done
check_valid -. "retry up to 2" .-> draft_frontend_blueprint
classDef gated stroke:#B45309,stroke-width:2px
Shapes: rectangle = agent attempt · double rectangle = tool call · stadium = human decision · diamond = condition evaluated by the engine over recorded outputs · parallelogram = fan-out or join · circle = timer · cylinder = sub-workflow · flag = compensation. A thick amber border marks a gated step; a dashed edge is a bounded on_false loop. A step with a when guard runs only when its predicate over recorded outputs holds; otherwise the engine records it Skipped and its dependants treat it as satisfied (ADR-0027).
Steps¶
| # | Step | Kind | Runs | Gate | Class | Depends on | Retry | Timeout | Compensation | What it does |
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | Derive the shell and microfrontendsderive-composition |
agent | frontend-developer |
none | read | — | exponential ×3 (30s) | PT30M | — | Maps the work areas and screens of the UX Blueprint to a shell and microfrontends and to the operations of the Service Blueprint. |
| 2 | Draft the Frontend Blueprintdraft-frontend-blueprint |
agent | frontend-developer |
none | sandbox | derive-composition | exponential ×3 (30s) | PT30M | — | Writes the Frontend Blueprint: shell, microfrontends, routes, state families, locales, accessibility contracts and API bindings. |
| 3 | Submit the Draft versionsubmit-version |
tool | blueprint-submit-version |
none | shared-write | draft-frontend-blueprint | fixed ×2 (10s) | PT2M | — | Stores the document as a project-scope Draft BlueprintVersion of its kind (idempotent on document hash); a shared write that the project policy may gate; Draft versions are autonomous by default (D64). |
| 4 | Validate the blueprintvalidate |
tool | blueprint-validate |
none | sandbox | submit-version | fixed ×2 (10s) | PT5M | — | BlueprintService validates the version against blueprint-frontend-v1 and its rule set and returns a receipt; BlueprintValidated is emitted with passed true or false. |
| 5 | Validation passed?check-valid |
condition | engine | none | read | validate | none | PT1M | — | Engine condition over the recorded receipt; findings go back to the draft step up to twice, then the run fails with the report. Condition: steps.validate.validation-receipt.passed == true. On false: back to draft-frontend-blueprint up to 2 time(s) with steps.validate.validation-receipt. |
Step contracts¶
| Step | Inputs (name ← source) | Outputs (name: descriptor) |
|---|---|---|
derive-composition |
ux-blueprint ← input.ux-blueprintservice-blueprint ← input.service-blueprint |
composition: artifact-v1 |
draft-frontend-blueprint |
ux-blueprint ← input.ux-blueprintservice-blueprint ← input.service-blueprintcomposition ← steps.derive-composition.composition |
frontend-blueprint-draft: blueprint-frontend-v1 |
submit-version |
document ← steps.draft-frontend-blueprint.frontend-blueprint-draft |
version-ref: blueprint-version-ref-v1 |
validate |
version-ref ← steps.submit-version.version-ref |
validation-receipt: blueprint-validation-receipt-v1 |
Every mapping names its source (input.* a workflow input, steps.* an ancestor's recorded output, bundle.* a readiness member) and the validator checks that every required input of the step's agent is mapped and that descriptors agree. |
Gates and approvals¶
- shared-write: creating a Draft blueprint version in project scope is autonomous unless the project policy (BC-20) gates blueprint drafts, in which case an approval bound to the document hash is requested (D64) Compensation steps run in reverse order of the succeeded steps on failure after the last checkpoint; a step without a compensation leaves its sandbox output in place and the run ends Failed with the evidence (ADR-0014, recovery not replay).
Inputs, outputs and events¶
| Direction | Name | Descriptor | Required |
|---|---|---|---|
| in | service-blueprint | blueprint-service-v1 |
yes |
| in | ux-blueprint | blueprint-ux-v1 |
yes |
| out | frontend-blueprint | blueprint-frontend-v1 |
yes |
| out | validation-receipt | blueprint-validation-receipt-v1 |
yes |
Starts on RunAccepted from RunControlService when payload.workflowId == 'frontend-blueprint'; emits BlueprintValidated, plus the engine's WorkflowRunStarted, StepReady, StepRunStateChanged and WorkflowRunCompleted / WorkflowRunFailed and Run Control's run and attempt events (ADR-0014).
Decisions and traceability¶
- FR: FR-06 Exact-version approvals · FR-11 Compatible templates and libraries through release gates
- FUX: FUX-11 Software Factory journey
- XL: XL-08 Evaluate before promotion · XL-09 Generation yields a usable consumer
- ADRs: ADR-0014, ADR-0024, ADR-0026, ADR-0027 · ADR index
Definition authored 2026-11-05 to close the generation input gap (ADR-0027, D66); Draft until an evaluation gate (ADR-0021) and a review publish it as a BC-04 asset release. Validation is a tool call with a receipt and a bounded on_false loop (ADR-0026, D61).