Template Registry

Target Architecture — Final-State Design

The TemplateRegistryService, TemplateVersionService, and TemplateParameterService described here are the planned ConnectSoft.Factory.Templates.* services that govern the template catalog. The templates they catalog are real, implemented ConnectSoft.Template.* assets (see the Implemented callout below).

The Template Registry is the system of record for every code generator in the factory. It holds the identity, metadata, version history, and parameter contracts of each template so that agents and authors can discover the right generator, pin it to an exact version, and invoke it with valid inputs. It is the entry point of the template-first discipline: nothing is generated from an unregistered, unversioned source.

The registry is built from three cooperating aggregate roots and their owning services.

Aggregate roots

erDiagram
    Template ||--o{ TemplateVersion : "has versions"
    TemplateVersion ||--|| TemplateParameterSchema : "defines parameters"
    Template {
        string templateId
        string name
        string category
        string status
    }
    TemplateVersion {
        string templateVersionId
        string semanticVersion
        string sourceRef
        string payloadBlobRef
    }
    TemplateParameterSchema {
        string schemaId
        string jsonSchemaRef
        int parameterCount
    }

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

Template

Template is the stable, version-independent identity of a generator. It carries the canonical name (ConnectSoft.Template.Microservice), a human title, a category (service, library, client, mfe, saas, documentation, platform), an owner, lifecycle status (Draft, Active, Deprecated, Retired), and the set of tags used for discovery. It owns its TemplateVersion children and never holds executable payload directly. See Aggregate Roots.

TemplateVersion

TemplateVersion is an immutable, semantically versioned snapshot of a template's generator content. Each version references its Git source (sourceRef) and the packaged payload stored in Azure Blob (payloadBlobRef), plus the engine kind (dotnet new template pack or base-template folder), a changelog, and the minimum runtime target (e.g. .NET 10). Versions move through Draft → Validated → Published → Deprecated. Once published, a version is immutable so that any past ScaffoldOutput remains reproducible.

TemplateParameterSchema

TemplateParameterSchema is the typed input contract for a TemplateVersion. It is expressed as a JSON Schema describing each parameter's name, type, constraints, default, whether it is required, and the conditional rules between parameters (e.g. "includeAuth requires authority"). The schema is what TemplateParameterService uses to validate parameter values before the Scaffold Engine executes the template.

Registration

Templates enter the catalog through TemplateRegistryService. Registration establishes the Template identity and is deliberately separate from version publishing, so that the catalog can advertise a template before its first version is fully validated.

The registration flow:

1. An author (in the Factory Studio) or an authoring agent calls POST /templates with name, category, and metadata.
2. TemplateRegistryService enforces name uniqueness within the tenant and the ConnectSoft.Template.* naming convention (see Naming Conventions).
3. The service persists the Template aggregate and emits TemplateRegistered.
4. The Knowledge Platform indexes the new template so agents can discover it by category and tag.

sequenceDiagram
    participant Author as "Author / Agent"
    participant Reg as "TemplateRegistryService"
    participant Ver as "TemplateVersionService"
    participant Param as "TemplateParameterService"
    participant Val as "TemplateValidationService"
    Author->>Reg: POST /templates
    Reg-->>Author: templateId (TemplateRegistered)
    Author->>Ver: POST /templates/{templateId}/versions
    Ver->>Param: register parameter schema
    Param-->>Ver: schemaId
    Ver->>Val: request validation (async)
    Val-->>Ver: TemplateValidated
    Ver-->>Author: templateVersionId (TemplateVersionCreated)

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

Versioning

TemplateVersionService owns the TemplateVersion lifecycle and enforces semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR — breaking changes to the generated structure or the parameter schema (a parameter removed or made required, generated layout changed in an incompatible way).
• MINOR — additive, backward-compatible changes (new optional parameter, new generated file that does not break existing consumers).
• PATCH — fixes that do not change the generated contract.

Each new version is created from a Git source reference, packaged into a Blob payload, and submitted to TemplateValidationService. Only after TemplateValidated succeeds can TemplatePublishingService move it to Published. The registry keeps the full version history; consumers pin an exact semanticVersion or a range, and the registry resolves the highest compatible published version.

Deprecation and retirement are first-class: marking a version Deprecated keeps it usable but flags it in compatibility evaluations and triggers TemplateUpgradeService to compute upgrade plans for downstream products.

Parameters

TemplateParameterService manages TemplateParameterSchema documents and the validation of supplied values. A typical parameter set for a service template:

{
  "serviceName": "Reservations",
  "namespaceRoot": "Contoso.Booking",
  "persistence": "PostgreSQL",
  "messaging": "MassTransit",
  "includeAuthorization": true,
  "authority": "https://identity.contoso.com",
  "targetFramework": "net10.0"
}

When the Scaffold Engine is invoked, parameter values are validated against the version's schema: types are checked, required values asserted, enum values constrained (e.g. persistence ∈ the implemented PersistenceModel.* flavors), and conditional rules evaluated. Invalid input fails fast with a structured error before any generation occurs — agents receive the validation errors and can correct and retry autonomously.

Real templates governed by the registry

Implemented

The following ConnectSoft.Template.* assets exist in the codebase as dotnet new template packs and base-template folders targeting .NET 10, published to Azure Artifacts. The registry is the final-state catalog that versions and governs them.

Template	Category	Generates
MicroserviceTemplate	service	Clean Architecture microservice (Api/Application/DomainModel/PersistenceModel/FlowModel)
BaseTemplate	service	Shared base solution layout for services
WorkerTemplate	service	Background worker / message consumer host
ApiGatewayTemplate	service	API gateway / edge host
AuthorizationServerTemplate	service	OpenIddict authorization server
IdentityTemplate	service	Identity / user management service
HealthChecksAggregatorTemplate	service	Health-check aggregation endpoint
LibraryTemplate	library	Reusable .NET library package
ApiLibraryTemplate	library	API client library package
AISkillsLibraryTemplate	library	Agent skills library
PlatformTemplate	platform	Composite platform solution
DocumentationTemplate	documentation	MkDocs documentation site
MarketingSiteTemplate	documentation	Marketing site
MauiBaseTemplate	client	MAUI cross-platform app base
AI.SoftwareFactory.AgentTemplate	client	Agent host (Microsoft Agent Framework + MCP)
Blazor.ShellTemplate	mfe	Blazor MFE shell host
Blazor.ComponentLibraryTemplate	mfe	Blazor component library
Blazor.MicrofrontendLibraryTemplate	mfe	Blazor micro-frontend library
Blazor.Mfe.AIChat	mfe	AI chat micro-frontend
Blazor.Mfe.Identity.Admin	mfe	Identity admin micro-frontend
Blazor.Mfe.Identity.SelfService	mfe	Identity self-service micro-frontend
Blazor.Mfe.AuthorizationServer.Admin	mfe	Authorization server admin micro-frontend
Blazor.Mfe.Logistics	mfe	Logistics micro-frontend
Saas.TenantsTemplate	saas	Tenant management service
Saas.EntitlementsTemplate	saas	Entitlements service
Saas.BillingTemplate	saas	Billing service
Saas.MeteringTemplate	saas	Metering service
Saas.ProductsCatalogTemplate	saas	Products catalog service

Agent runtime templates

AI.SoftwareFactory.AgentTemplate generates agent hosts on the Microsoft Agent Framework with ConnectSoft.Extensions.ModelContextProtocol for tool access — consistent with the Agent Mesh runtime.

How agents and authors use the registry

• Discovery — GET /templates/{templateId} and category/tag search return the template, its published versions, and each version's parameter schema. Agents query by category to find, for example, all service generators.
• Pinning — a solution plan records the exact templateVersionId used so the result is reproducible.
• Validation-first — parameters are validated against the schema before execution, eliminating a whole class of generation failures.
• Provenance — registration and versioning emit TemplateRegistered, TemplateVersionCreated, and TemplatePublished into the event envelope, feeding traceability and the artifact metadata model.

Related

• Library Registry
• Scaffold Engine
• Compatibility Model
• Aggregate Roots
• APIs
• Templates Overview (implementation)
• Template Architecture (implementation)