Events¶

Target Architecture — Final-State Design

The commands and events below are the planned message contracts of the ConnectSoft.Factory.Templates.* services. All travel in the canonical event envelope on Azure Service Bus via ConnectSoft.Extensions.MessagingModel.MassTransit. Events are NounVerbPastTense; commands are VerbNoun (see Naming Conventions).

Every meaningful action in the platform emits an event, making generation traceable, replayable, and observable. Commands express intent into the platform; domain events record facts within it; integration events promote those facts to cross-platform contracts consumed by the Knowledge, Marketplace, DevOps, and Observability platforms.

Commands (VerbNoun)¶

Command	Handled by	Purpose
`RegisterTemplate`	TemplateRegistryService	Create a template identity
`CreateTemplateVersion`	TemplateVersionService	Snapshot a new template version
`ValidateTemplate`	TemplateValidationService	Run validation checks on a version
`PublishTemplate`	TemplatePublishingService	Promote a validated version to Published
`GenerateScaffold`	ScaffoldEngineService	Execute a template and produce output
`EvaluateCompatibility`	TemplateCompatibilityService / CompatibilityMatrixService	Evaluate a composition
`PlanTemplateUpgrade`	TemplateUpgradeService	Compute an upgrade plan
`RegisterLibrary`	LibraryRegistryService	Create a library identity
`CreateLibraryVersion`	LibraryVersionService	Record a library release
`ScanDependencies`	DependencyAnalyzerService	Resolve a version's dependency graph
`PublishPackage`	PackagePublisherService	Push a package to Azure Artifacts
`AdvisePackageUpgrade`	PackageUpgradeAdvisorService	Recommend upgrade paths

Domain events (NounVerbPastTense)¶

Emitted by aggregates within the platform:

Event	Source aggregate	Meaning
`TemplateRegistered`	Template	A template identity was created
`TemplateVersionCreated`	TemplateVersion	A new version snapshot was created
`TemplateParameterSchemaDefined`	TemplateParameterSchema	A version's parameter schema was set
`TemplateValidated`	TemplateValidationResult	A version passed/failed validation
`TemplatePublished`	TemplatePublication	A version was promoted to Published
`TemplateExecutionRequested`	TemplateExecution	An execution was accepted
`ScaffoldGenerated`	ScaffoldOutput	Scaffold output was produced
`TemplateExecuted`	TemplateExecution	An execution completed and was committed
`CompatibilityEvaluated`	CompatibilityMatrix	A composition was evaluated
`TemplateUpgradePlanCreated`	TemplateUpgradePlan	An upgrade plan was computed
`LibraryRegistered`	LibraryPackage	A library identity was created
`LibraryVersionCreated`	LibraryVersion	A library release was recorded
`DependencyScanned`	DependencyGraph	A version's dependencies were resolved
`LibraryPublished`	PackagePublication	A package was published to Azure Artifacts
`ApiClientCataloged`	LibraryPackage (client facet)	An API client was cataloged

Integration events¶

The following domain events are promoted to versioned cross-platform contracts (listed in the Event Catalog sibling catalogs):

Integration event	Primary consumers	Why it crosses the boundary
`TemplatePublished`	Knowledge, Marketplace, DevOps	A new generator is available for selection and discovery
`TemplateVersionCreated`	Knowledge	Keeps the "what can be built" graph current
`TemplateExecuted`	DevOps, Knowledge, Observability	Hands generated output to delivery; records provenance
`ScaffoldGenerated`	DevOps, Observability	The buildable artifact is ready
`TemplateValidated`	Governance, Observability	Validation outcome feeds quality gates
`CompatibilityEvaluated`	Observability, Agent Mesh	Compatibility outcomes inform agent self-correction
`LibraryPublished`	Knowledge, Marketplace, DevOps	A new reusable package is available
`DependencyScanned`	Governance, Knowledge	Dependency/CVE intelligence and impact analysis

The eight headline events called out across the platform are: TemplatePublished, TemplateVersionCreated, TemplateExecuted, ScaffoldGenerated, TemplateValidated, CompatibilityEvaluated, LibraryPublished, DependencyScanned.

Envelope¶

Every event uses the canonical event envelope. Example for ScaffoldGenerated:

{
  "eventId": "evt-9b1c4d2a",
  "eventType": "ScaffoldGenerated",
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "traceId": "trace-7f2a91",
  "correlationId": "corr-4d21",
  "causationId": "evt-execution-requested-id",
  "occurredAt": "2026-06-11T09:05:00Z",
  "payload": {
    "executionId": "exec-9a2b",
    "scaffoldOutputId": "scaf-31c8",
    "templateId": "tmpl-7c1a9f",
    "templateVersionId": "tver-3201",
    "libraries": [
      { "packageName": "ConnectSoft.Extensions.PersistenceModel.PostgreSQL", "version": "4.1.0" }
    ],
    "repository": "git:contoso/booking-reservations",
    "contentHash": "sha256:..."
  }
}

The correlationId (corr-4d21) ties the scaffold back to the originating agent task-4d21; causationId chains it to the TemplateExecutionRequested event. Selected fields mirror into Service Bus application properties (cs-event-type, cs-tenant-id, cs-trace-id, cs-correlation-id) for subscription filtering without deserializing the body.

Topics¶

Events are published to Azure Service Bus topics, with subscriptions per consumer. The platform uses two domain topics plus the shared factory integration topic:

Topic	Carries	Subscribers
`factory.templates.template`	template domain events	Knowledge, Marketplace, DevOps, Observability, internal workers
`factory.templates.library`	library domain events	Knowledge, Marketplace, Governance, internal workers
`factory.integration`	promoted integration events	cross-platform consumers (shared envelope contract)

Subscriptions filter on cs-event-type and cs-tenant-id application properties. Commands are sent to per-service queues (factory.templates.{service}.commands), not topics, since each command is handled by exactly one aggregate.

Event-flow diagram¶

flowchart LR
    subgraph TemplateLifecycle["Template lifecycle"]
        Reg["TemplateRegistered"] --> Ver["TemplateVersionCreated"]
        Ver --> Val["TemplateValidated"]
        Val --> Pub["TemplatePublished"]
        Pub --> Exec["TemplateExecuted"]
        Exec --> Scaf["ScaffoldGenerated"]
    end
    subgraph LibraryLifecycle["Library lifecycle"]
        LReg["LibraryRegistered"] --> LVer["LibraryVersionCreated"]
        LVer --> Dep["DependencyScanned"]
        Dep --> LPub["LibraryPublished"]
    end
    Pub --> CEval["CompatibilityEvaluated"]
    Dep --> CEval
    Scaf --> DevOps["DevOps &amp; GitOps"]
    Pub --> Knowledge["Knowledge Platform"]
    LPub --> Marketplace["Marketplace"]
    CEval --> Observability["Observability &amp; Feedback"]

Hold "Alt" / "Option" to enable pan & zoom