Delivery map: AsyncAPI / Event Documentation Pipeline #4

Destination

The full event-documentation lifecycle running end-to-end — C# AsyncAPI generation library, spec validation, CI/CD + GitHub workflow integration, auto-publish to the DevHub catalogue, and developer guidelines/templates — adopted by at least one pilot workload.

Notes

• Domain: event-driven API documentation (AsyncAPI)
• Jira: INTPLAT-764 (C# library), 761 (spec validation), 763 (build pipeline integration), 765 (GitHub workflows for event validation), 762 (publish to DevHub), 760 (usage guidelines & templates)
• These stories are not epic-linked in Jira; this map is their tracking parent
• Pipeline order: 764 → 761 → 763/765 → 762 → 760
• Prefer annotations/attributes over hand-written docs; minimal manual intervention in CI

Decisions so far

• 2026-09-07 — How should the C# AsyncAPI generation library work (annotations, extension methods, spec version)? #15 (research) resolved: DevHub = Spotify Backstage instance (759 API entities). Ingestion is file-based: curated kind: API YAML in backstage.idp.configs/catalog/apis/ (URL location, 4h processing) or per-repo catalog-info.yaml auto-ingestion. AsyncAPI is a first-class spec.type; entity format, $text definition references, Soundcheck governance, and a catalog-write CI service token (BACKEND_SECRET_GHA) are all evidenced. Six copyable automated-publishing examples found (closest: catalog-info-update.yml). Full report: comment on How should the C# AsyncAPI generation library work (annotations, extension methods, spec version)? #15.

• 2026-09-07 — Coordinate INTPLAT-51: assign API-33173 and confirm NZ dataset status #14 (planning) resolved: BKG async-operation manifest design settled. Core: per-domain {domain}.Bkg.Index code-first manifest (IOP-mirrored, asymmetric — publish = topic + ACL + payload type + provided schema ref; subscribe = queue ← n topic bindings each with own contract) in usecase family Bunnings.UseCase.AspNetCore.Bkg (dotnet.common, alongside WebApi IOP usecase). Code is source of truth; index generates compatible subscriptions.json (provisioning tooling unchanged — Phase 0 hard gate). AsyncAPI = 3.0, emitted by a hand-rolled zero-dependency minimal 3.0 emitter (no external packages). Schemas are PROVIDED, not generated (JSON Schema/XSD/other per content type; XSD/CSV ride bindings or x- extensions). Exporter = Spectre.Console CLI in the existing Bunnings.UseCase.AspNetCore.Tools* family (ProductExporterTool precedent) exporting subscriptions.json + asyncapi.yaml. Phases: 0 spike on item (byte-compat gate + publish-ACL example), 1 core usecase + EMP builder integration, 2 exporter tool, 3 pilot adoption feeding What does DevHub expect for event-doc publishing (format, API, auth)? #16/#763/765/762. Details: plan comment on Coordinate INTPLAT-51: assign API-33173 and confirm NZ dataset status #14.

• 2026-09-07 — What does DevHub expect for event-doc publishing (format, API, auth)? #16 (planning) resolved: validation strategy settled. Validator = official @asyncapi/cli via npx on Node 20 (org convention; C# validator not viable — stable AsyncAPI.NET is 2.x models, no validation; 3.0 support confirmed by spike). Runs as a per-domain PR workflow first (pilot item, validate-docs.yml precedent), then promoted to a shared reusable workflow in GHA.API.Templates (765 roll-out). Four checks, all blocking required on PRs: (1) drift — regenerate from {domain}.Bkg.Index, fail on diff (needs byte-stable emitter serialization), (2) 3.0 conformance via @asyncapi/cli (warnings-as-errors), (3) subscriptions.json against a manifest JSON Schema (bridge contract for the existing solace-events artefact flow), (4) provided schema refs exist and parse. Out of scope: Soundcheck/DevHub governance (post-publish, 762). Details: plan comment on What does DevHub expect for event-doc publishing (format, API, auth)? #16.

• 2026-09-07 — Where and how should AsyncAPI validation run (GitHub workflows vs CI)? #17 (task) resolved: pilot workload = item (second pilot: loyalty). Rationale: item ticks all three criteria (event-heavy — 6 queues/13 topic subs with wildcard + sourceType-specific patterns; healthy pipeline — IOP pr-build with active solace-events artefact flow; willing owner — bmazzarol), and Coordinate INTPLAT-51: assign API-33173 and confirm NZ dataset status #14's Phase 0 spike is already scoped on item so spike and pilot de-risk the same workload. Loyalty chosen as second pilot for cross-domain consumption (ITM events) + manifest shape variant (no pagerDuty key). Details: decision comment on Where and how should AsyncAPI validation run (GitHub workflows vs CI)? #17.

Not yet specified

• Pilot workload selection — library design done (item is the natural Phase 0 candidate); decide in Where and how should AsyncAPI validation run (GitHub workflows vs CI)? #17.

Out of scope

• Changes to event contracts themselves (schemas stay as-is; docs are generated from them).
• OpenAPI (sync) documentation — this stream is events/AsyncAPI only.

Activity log

• 2026-09-07 — map created; destination approved by user.

• 2026-09-07 — destination approved by user; mapped 4 frontier tickets (Coordinate INTPLAT-51: assign API-33173 and confirm NZ dataset status #14–Where and how should AsyncAPI validation run (GitHub workflows vs CI)? #17).

• 2026-09-07 — research phase started: How should the C# AsyncAPI generation library work (annotations, extension methods, spec version)? #15 claimed, explore agent research-devhub-ingestion spawned (DevHub ingestion research).

• 2026-09-07 — research agent relaunched with corrected model: How should the C# AsyncAPI generation library work (annotations, extension methods, spec version)? #15 → research-devhub-ingestion-2.

• 2026-09-07 — How should the C# AsyncAPI generation library work (annotations, extension methods, spec version)? #15 (research) resolved by explore agent research-devhub-ingestion-2: report posted to How should the C# AsyncAPI generation library work (annotations, extension methods, spec version)? #15, ticket closed; findings reconciled above. Frontier now: Coordinate INTPLAT-51: assign API-33173 and confirm NZ dataset status #14 (AsyncAPI library design) and What does DevHub expect for event-doc publishing (format, API, auth)? #16 (validation strategy) unblocked; Where and how should AsyncAPI validation run (GitHub workflows vs CI)? #17 (pilot) next behind them.

• 2026-09-07 — Coordinate INTPLAT-51: assign API-33173 and confirm NZ dataset status #14 (planning) claimed; context gathered (IOP index pattern, events/subscriptions.json manifests, SolaceSmfClientFactory inputs, external AsyncAPI .NET options); design tree worked with user (8 decisions); plan posted to Coordinate INTPLAT-51: assign API-33173 and confirm NZ dataset status #14, ticket closed.

• 2026-09-07 — What does DevHub expect for event-doc publishing (format, API, auth)? #16 (planning) claimed; context gathered (org IOP build workflows, Node 20 convention, validate-docs precedent, solace-events artefact flow, C# validator viability); design tree worked with user (3 decisions); plan posted to What does DevHub expect for event-doc publishing (format, API, auth)? #16, ticket closed. Only frontier ticket left on this map: Where and how should AsyncAPI validation run (GitHub workflows vs CI)? #17 (pilot selection).

• 2026-09-07 — Where and how should AsyncAPI validation run (GitHub workflows vs CI)? #17 (task) claimed; candidate data gathered (item/loyalty/receipts/communications/authserver.admin event footprints); pilot decided with user (item; loyalty second); decision posted to Where and how should AsyncAPI validation run (GitHub workflows vs CI)? #17 with rationale recorded in Assets, ticket closed. All frontier tickets on this map are now resolved.

• 2026-09-07 — Firmed designs written back to Jira: Design (agreed 2026-09-07) sections appended to INTPLAT-761/763/764/765 descriptions (760/762 untouched — no firmed design yet; 762 has research only).

Status as of 2026-10-07

Net: All design/planning work is complete (resolved 2026-09-07). No implementation has started. The pipeline (764 → 761 → 763/765 → 762 → 760) is sequenced and ready to begin with the Phase 0 spike on item.

Activity log (continued)

• 2026-10-07 — Status refresh: no changes. All six stories remain Backlog. Implementation not yet started; next step is the Phase 0 spike on item (byte-compat gate + publish-ACL example).