Skip to content

Scaffold Engine

Target Architecture — Final-State Design

ScaffoldEngineService and the TemplateExecution/ScaffoldOutput aggregates described here are the planned ConnectSoft.Factory.Templates.ScaffoldEngineService decomposition. It executes the real, implemented ConnectSoft.Template.* generators cataloged in the Template Registry.

The Scaffold Engine is where intent becomes code. Given a registered TemplateVersion and a validated set of parameters, ScaffoldEngineService executes the generator and produces a ScaffoldOutput — a complete, buildable solution artifact with full provenance. It is the deterministic heart of the factory machinery: the same template version and parameters always yield an equivalent output, and every output is traceable back to its inputs and the agent task that requested it.

Template-to-generation flow

sequenceDiagram
    participant Mesh as "Agent Mesh"
    participant Engine as "ScaffoldEngineService"
    participant Param as "TemplateParameterService"
    participant Compat as "TemplateCompatibilityService"
    participant Ver as "TemplateVersionService"
    participant Blob as "Azure Blob"
    participant Git as "Git source registry"
    participant DevOps as "DevOps & GitOps"

    Mesh->>Engine: POST /templates/{templateId}/execute
    Engine->>Param: validate parameters vs schema
    Param-->>Engine: valid
    Engine->>Compat: evaluate template + library + runtime
    Compat-->>Engine: compatible
    Engine->>Ver: resolve published TemplateVersion
    Ver-->>Engine: payloadBlobRef + sourceRef
    Engine->>Blob: fetch template payload
    Engine->>Engine: execute generator (TemplateExecution)
    Engine->>Blob: store ScaffoldOutput payload
    Engine->>Git: commit scaffold to repository
    Engine-->>Mesh: ScaffoldOutput (ScaffoldGenerated)
    Engine->>DevOps: hand off for build + deploy
Hold "Alt" / "Option" to enable pan & zoom

The flow is intentionally validation-first and compatibility-gated: nothing is generated until parameters pass the schema and the Compatibility Model confirms the requested template, library set, and runtime are mutually compatible. This eliminates the most common classes of broken generation before any work is done.

TemplateExecution lifecycle

TemplateExecution is the aggregate that tracks a single run of the engine from request to result. It is the unit of traceability for generation.

stateDiagram-v2
    [*] --> Requested
    Requested --> Validating
    Validating --> Rejected : parameter or compatibility failure
    Validating --> Generating : valid and compatible
    Generating --> Generated : output produced
    Generating --> Failed : engine error
    Generated --> Committed : pushed to Git
    Committed --> [*]
    Rejected --> [*]
    Failed --> [*]
Hold "Alt" / "Option" to enable pan & zoom
State Meaning Event emitted
Requested Execution accepted, inputs captured TemplateExecutionRequested
Validating Parameters and compatibility being checked —
Rejected Validation or compatibility failed; structured errors returned TemplateExecutionRejected
Generating Generator running against the payload —
Generated ScaffoldOutput produced and stored ScaffoldGenerated
Failed Engine error during generation TemplateExecutionFailed
Committed Output committed to Git and handed to DevOps TemplateExecuted

Each execution records the templateVersionId, the resolved library version set, the parameter values, the requesting agent task- id, and the resulting ScaffoldOutput id. The correlationId from the event envelope ties the whole chain together so the Knowledge Platform and Observability & Feedback platforms can correlate the generated artifact to the agent decision that produced it.

ScaffoldOutput

ScaffoldOutput is the immutable result aggregate (see Aggregate Roots). It captures:

  • The generated payload (the solution tree) stored in Azure Blob and committed to a Git repository.
  • The provenance manifest — template id and version, library versions, parameter values, engine kind, and the originating execution id.
  • The target coordinates — destination repository, branch, and the DevOps pipeline definition to run.
  • A content hash so the output is verifiable and de-duplicable.

The manifest conforms to the artifact metadata model, so a ScaffoldOutput is a first-class, traceable factory artifact rather than an opaque ZIP.

Generation engines

The engine supports the two real authoring shapes used by ConnectSoft templates:

  • dotnet new template packs — templates packaged with a .template.config/template.json manifest. The engine invokes the .NET template engine with the validated parameters mapped to template symbols.
  • Base-template folders — pre-laid-out solution folders with token substitution. The engine clones the base layout and applies parameter substitution and conditional file inclusion.

Both produce the same ScaffoldOutput shape, so downstream consumers are agnostic to the authoring style. The engine targets .NET 10 outputs and resolves library dependencies from Azure Artifacts.

Multi-template solutions

A single solution plan from the Agent Mesh often requires several templates — for example a SaaS product needs Saas.TenantsTemplate, Saas.BillingTemplate, an ApiGatewayTemplate, an AuthorizationServerTemplate, a Blazor.ShellTemplate, and several Blazor.Mfe.* micro-frontends. The engine executes these as a coordinated batch sharing one correlationId, producing one ScaffoldOutput per template plus a composition manifest that DevOps uses to wire them into a single repository/solution. Cross-template compatibility is evaluated once for the whole set.

Determinism, idempotency, and re-scaffolding

  • Determinism — published TemplateVersion payloads are immutable, so re-running an execution with the same inputs yields an equivalent output (modulo timestamps), which the content hash confirms.
  • Idempotency — executions deduplicate on the request's idempotency key; a retried TemplateScaffoldWorker message will not generate twice (see Workers).
  • Re-scaffolding — when TemplateUpgradeService produces a TemplateUpgradePlan, the engine can re-execute against a newer template version to regenerate or diff a product, supporting safe, governed upgrades of the Generated SaaS Product.

How the engine is driven

  • Agent Mesh calls POST /templates/{templateId}/execute with parameters and a target repository, supplying the agent task- id as correlation. This is the primary path. See APIs.
  • The TemplateScaffoldWorker runs executions asynchronously for large or batched generation, reacting to a GenerateScaffold command.
  • Factory Studio offers a human-driven path for authors to test a template version with sample parameters before publishing.