Skip to content

Control Plane — Events & Commands

The Control Plane is event-driven end to end. Commands express intent, aggregate roots emit domain events as facts, and selected domain events are promoted to integration events that cross platform boundaries. Everything travels in the canonical event envelope on Azure Service Bus via MassTransit, which is what makes the factory traceable, replayable, and observable.

Target Architecture — Final-State Design

Naming follows the conventions: commands are VerbNoun, domain/integration events are NounVerbPastTense. Breaking event changes append a version suffix (UsageRecordedV2) and bump cs-schema-version.

Canonical Envelope

Every message uses the standard envelope; only payload varies by eventType.

{
  "eventId": "evt-7b3c1f9a-2e44-4c1a-9b6d-0f2a8c3d5e10",
  "eventType": "WorkflowInstanceStarted",
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "traceId": "trace-9f1c2b7d",
  "correlationId": "corr-3a6e1d40",
  "causationId": "evt-projectcreated-1",
  "occurredAt": "2026-06-11T00:00:00Z",
  "payload": {
    "workflowInstanceId": "wf-7781",
    "workflowDefinitionId": "wfd-project-bootstrap",
    "workflowDefinitionVersion": "4.1.0"
  }
}

Field semantics are defined in the Event Envelope reference; identity fields are a superset of the Metadata Schema.

Commands (VerbNoun)

Commands are imperative requests handled by exactly one aggregate; they are not part of the public event stream.

Command Handled by Effect
ProvisionTenant TenantService Create and isolate a new tenant.
CreateProject ProjectService Register a factory project.
ValidateBlueprint BlueprintValidatorService Run validation on a blueprint version.
StartWorkflow WorkflowOrchestrator Instantiate a workflow from a definition.
AssignAgentTask TaskAssignmentService Place an agent task for a workflow step.
EvaluatePolicy PolicyEngineService Produce a policy decision for an action.
RequestApproval ApprovalService Open a human approval gate.
GrantApproval ApprovalService Resolve an approval gate.
RecordUsage CostUsageService Record a metered consumption fact.
ReplayWorkflow WorkflowReplayService Deterministically replay an instance.

Domain Events (NounVerbPastTense)

Facts emitted by aggregates after a state change, published within the Control Plane. Representative set:

Event Emitting aggregate Meaning
TenantProvisioned Tenant A tenant was created and isolated.
SubscriptionActivated Subscription A tenant's edition subscription became active.
ProjectCreated Project A factory project was registered.
EnvironmentProvisioned Environment A project environment was provisioned.
ModuleRegistered Module A module was added to the catalogue.
BlueprintValidated Blueprint A blueprint version passed validation.
WorkflowInstanceStarted WorkflowInstance A workflow instance began running.
WorkflowStepCompleted WorkflowInstance A workflow step finished.
AgentTaskAssigned AgentTask A task was placed for an agent.
AgentTaskCompleted AgentTask An agent finished a task with validated output.
ApprovalRequested ApprovalRequest A human approval gate opened.
ApprovalGranted ApprovalRequest An approval gate was granted.
PolicyDecisionRecorded PolicyDecision A policy decision was made and recorded.
AuditEntryRecorded AuditEntry A governed action was written to the audit trail.
UsageRecorded UsageRecord A consumption fact was metered.

Integration Events

Domain events promoted to versioned, cross-platform contracts consumed by other factory platforms:

Integration event Produced by Primary consumers
WorkflowInstanceStarted / WorkflowInstanceCompleted Workflow Orchestration Observability & Feedback, Knowledge Platform
AgentTaskAssigned / AgentTaskCompleted Workflow Orchestration Agent Mesh, Knowledge Platform
BlueprintValidated Blueprint Management Factory Studio, Knowledge Platform
PolicyDecisionRecorded Governance Governance, Security & Compliance
ApprovalRequested / ApprovalGranted Governance Factory Studio (Human Review Center)
UsageRecorded / UsageRolledUp Cost & Usage Tenant & Edition (quota), billing
ArtifactCreated Artifact Management Knowledge Platform, DevOps & GitOps

Service Bus Topics & Subscriptions

Events are published to context-aligned topics; consumers subscribe with rule filters on broker application properties (cs-event-type, cs-tenant-id, cs-correlation-id) so they filter without deserializing the body.

Topic Publishers Example subscribers
control-plane.tenancy TenantService, SubscriptionService, QuotaService Project Management, Cost & Usage
control-plane.projects ProjectService, EnvironmentService, ModuleCatalogService Workflow Orchestration, Knowledge Platform
control-plane.blueprints BlueprintService, BlueprintValidatorService Workflow Orchestration, Factory Studio
control-plane.workflows WorkflowOrchestrator, TaskAssignmentService Agent Mesh, ProcessStateService, Observability
control-plane.governance PolicyEngineService, ApprovalService, AuditService Governance platform, Factory Studio
control-plane.usage CostUsageService Tenant & Edition, billing
control-plane.artifacts ArtifactService, LineageService Knowledge Platform, DevOps & GitOps

Event Correlation Flow

A single traceId is minted when intent enters the factory and propagates through every event; correlationId groups one workflow; causationId chains cause to effect.

flowchart TB
    ProjectCreated["ProjectCreated<br/>traceId=T, corr=C, cause=null"] --> WorkflowInstanceStarted["WorkflowInstanceStarted<br/>cause=ProjectCreated"]
    WorkflowInstanceStarted --> BlueprintValidated["BlueprintValidated<br/>cause=WorkflowInstanceStarted"]
    BlueprintValidated --> AgentTaskAssigned["AgentTaskAssigned<br/>cause=BlueprintValidated"]
    AgentTaskAssigned --> AgentTaskCompleted["AgentTaskCompleted<br/>cause=AgentTaskAssigned"]
    AgentTaskCompleted --> ArtifactCreated["ArtifactCreated<br/>cause=AgentTaskCompleted"]
    AgentTaskCompleted --> UsageRecorded["UsageRecorded<br/>cause=AgentTaskCompleted"]
    ArtifactCreated --> PolicyDecisionRecorded["PolicyDecisionRecorded<br/>cause=ArtifactCreated"]
    PolicyDecisionRecorded --> ApprovalRequested["ApprovalRequested<br/>cause=PolicyDecisionRecorded"]
    ApprovalRequested --> ApprovalGranted["ApprovalGranted<br/>cause=ApprovalRequested"]
    ApprovalGranted --> WorkflowInstanceCompleted["WorkflowInstanceCompleted<br/>cause=ApprovalGranted"]
Hold "Alt" / "Option" to enable pan & zoom

Because every event shares traceId=T and correlationId=C, the Knowledge and Observability platforms can reconstruct the entire causation chain from business intent (ProjectCreated) to completed workflow (WorkflowInstanceCompleted).

Consumer Rules

  1. Idempotency — deduplicate on eventId; workers add an idempotency key.
  2. Tenant guard — assert tenantId before touching any store.
  3. Trace propagation — traceId/correlationId flow into spans and logs.
  4. Poison handling — unprocessable messages dead-letter with the full envelope preserved for replay.
  5. Forward compatibility — tolerate unknown payload fields and unknown eventType (ignore-and-log).