TemplateRegistryService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-14 Template Catalog
Platform / plane	Template & Library / Software Factory pack
Deployment granularity	module of host · host TemplateCatalogHost
Status	target · ConnectSoft.Factory.Templates.Catalog
Built from	connectsoft-microservice · libraries: connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-query-model
Decisions	ADR-0021
Traceability	FR-06 FUX-03 NFR-13 XL-03 XL-07

Purpose and responsibilities

TemplateRegistryService is the runtime truth of the ConnectSoft estate as building material. The Discoverer reads every template repository through connectors — .template.config short names, projects and their roles, switches with allowed values, generated and preserved paths, pipelines, docs — and pins each template version by manifest hash at a commit; it reads library versions and their packages from the feeds with their layer and capability area. The CompatibilityComputer fills the matrix: a template version with a library version, a runtime, an edition or a topology, Compatible only with evidence (a pipeline build, a conformance run), otherwise Unknown. Template versions become Published through Asset Publication like any asset.

It absorbs the June-2026 version, parameter, compatibility, library-registry, library-version, API-client and dependency rows; template upgrade and package upgrade advisors stay deferred.

Context and boundaries

flowchart LR
    S["TemplateRegistryService"]
    GenerationRecipeService["GenerationRecipeService"] -->|grpc| S
    AgentRuntimeWorker["AgentRuntimeWorker"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| ConnectorRegistryService["ConnectorRegistryService"]
    S -->|grpc| AgentRegistryService["AgentRegistryService"]
    S -->|grpc| RepositoryIntelligenceService["RepositoryIntelligenceService"]
    S -. "TemplateVersionDiscovered" .-> E_TemplateVersionDiscovered(("event"))
    S -. "TemplateVersionPublished" .-> E_TemplateVersionPublished(("event"))
    S -. "LibraryVersionDiscovered" .-> E_LibraryVersionDiscovered(("event"))
    S -. "CompatibilityChecked" .-> E_CompatibilityChecked(("event"))

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

The generated template catalog and library pages of this site (L1) are the design-time view; this service is what recipes and agents query at run time. A manifest is never edited in the catalog; a change is a commit in the template repository.

Domain model

TemplateVersion — A pinned manifest of one template version: short name, layer, projects and their roles (EntityModel … InfrastructureModel), template switches with allowed values, generated and preserved paths, pipelines, docs, consumers, the repository and commit it was read from, and its asset release. (catalog entry)

Field	Type	Required	Description
templateId	string	yes	Short name from .template.config (the templates catalog id).
version	string	yes
tenantId	string	yes	Platform tenant; templates are platform assets.
layer	enum:TemplateLayer	yes
repository	string	yes
commit	string	yes
manifest	json	yes	projects, switches, generated/preserved paths, pipelines, docs
manifestHash	string	yes
state	enum:CatalogState	yes
releaseId	string	no
discoveredAt	datetime	yes

Invariants:

• A manifest is read from the template repository at a commit and pinned by hash; it is never edited in the catalog.
• Only Published versions may be selected by a generation recipe; Deprecated versions may be upgraded from, never generated with.

Events: TemplateVersionDiscovered, TemplateVersionPublished · Tables: TemplateVersions · Repository: TemplateVersionRepository

LibraryVersion — One version of one library (the libraries catalog id): packages and their versions on the feed, layer, capability area, options sections and registration API as read from the repository, and the templates that consume it. (catalog entry)

Field	Type	Required	Description
libraryId	string	yes
version	string	yes
tenantId	string	yes
layer	enum:TemplateLayer	yes
area	string	yes
packages	json	yes
optionsSections	json	no
consumers	list:string	yes
state	enum:CatalogState	yes
discoveredAt	datetime	yes

Invariants:

• Package versions come from the feed; a library version without a published package is Discovered, not Published.

Events: LibraryVersionDiscovered · Tables: LibraryVersions · Repository: LibraryVersionRepository

CompatibilityEntry — One cell of the compatibility matrix: a template version with a library version, a runtime (for example .NET 9 or 10), a Factory edition or a topology, the result and its evidence (a pipeline run that built it, a conformance run). (catalog entry)

Field	Type	Required	Description
entryId	guid	yes
tenantId	string	yes
subjectKind	string	yes	template
subjectId	string	yes
subjectVersion	string	yes
withKind	string	yes	library
withId	string	yes
withVersion	string	no
result	enum:Compatibility	yes
evidenceRef	string	no
checkedAt	datetime	yes

Invariants:

• Compatible needs evidence (a build or conformance run); without evidence the result is Unknown.

Events: CompatibilityChecked · Tables: CompatibilityEntries · Repository: CompatibilityEntryRepository

erDiagram
    TemplateVersion {
        string templateId PK
        string version
        string tenantId
        enum_TemplateLayer layer
        string repository
        string commit
        json manifest
        string manifestHash
        enum_CatalogState state
        string releaseId
        datetime discoveredAt
    }
    LibraryVersion {
        string libraryId PK
        string version
        string tenantId
        enum_TemplateLayer layer
        string area
        json packages
        json optionsSections
        list_string consumers
        enum_CatalogState state
        datetime discoveredAt
    }
    CompatibilityEntry {
        guid entryId PK
        string tenantId
        string subjectKind
        string subjectId
        string subjectVersion
        string withKind
        string withId
        string withVersion
        enum_Compatibility result
        string evidenceRef
        datetime checkedAt
    }

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

Entities and value objects

None modelled

No entities or value objects are modelled for this item yet.

Data model and storage

Store	Role	Engine / profile	Tables
Template & Library store	primary	azure-sql / nhibernate-sqlserver	TemplateVersions, LibraryVersions, CompatibilityEntries

Table	Owner	Columns	Indexes
dbo.TemplateVersions	TemplateVersion	11	1
dbo.LibraryVersions	LibraryVersion	10	1
dbo.CompatibilityEntries	CompatibilityEntry	11	1

Full DDL: appendix.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/templates	ListTemplates	factory.catalog.read	read	natural	GW-03	Template versions with layer, state, switches and consumers (the generated template catalog at runtime).
GET	/factory/templates/{templateId}/versions/{version}	GetTemplateVersion	factory.catalog.read	read	natural	GW-03	The pinned manifest with projects, switches, generated and preserved paths, pipelines, docs and compatibility.
GET	/factory/libraries	ListLibraries	factory.catalog.read	read	natural	GW-03	Library versions by area and layer with packages and consumers.
GET	/factory/compatibility	QueryCompatibility	factory.catalog.read	read	natural	GW-03	Compatibility of a template or library version with libraries, runtimes, editions and topologies, with evidence.
POST	/factory/templates/discover	DiscoverTemplates	factory.catalog.admin	shared-write	natural	GW-03	Re-read template repositories and feeds now (Asset maintainer, Platform admin).
POST	/factory/templates/{templateId}/versions/{version}/publish	PublishTemplateVersion	factory.catalog.admin	publication	natural	GW-03	Submit a Verified template version to Asset Publication as a template release.

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Catalog	ResolveManifest	none	internal	read	Pinned manifest of a template version for recipes and agents.

Messages

Event	Topic	Scope / v	Aggregate	Consumers	Summary
TemplateVersionDiscovered	template-catalog.templates.v1.template-version-discovered	integration / 1	TemplateVersion	StudioBff, AuditService	A template version was read from its repository.
TemplateVersionPublished	template-catalog.templates.v1.template-version-published	integration / 1	TemplateVersion	GenerationRecipeService, FleetRolloutService, StudioBff, AuditService	A template version is Published (asset release exists).
LibraryVersionDiscovered	template-catalog.libraries.v1.library-version-discovered	integration / 1	LibraryVersion	StudioBff, GenerationRecipeService	A library version was read from the feed.
CompatibilityChecked	template-catalog.compatibility.v1.compatibility-checked	integration / 1	CompatibilityEntry	GenerationRecipeService, StudioBff	A compatibility cell was computed with evidence.

TemplateVersionDiscovered payload:

Field	Type	Required	Description
templateId	string	yes
version	string	yes
layer	enum:TemplateLayer	yes
commit	string	yes

TemplateVersionPublished payload:

Field	Type	Required	Description
templateId	string	yes
version	string	yes
layer	enum:TemplateLayer	yes
releaseId	string	yes

LibraryVersionDiscovered payload:

Field	Type	Required	Description
libraryId	string	yes
version	string	yes
area	string	yes
state	enum:CatalogState	yes

CompatibilityChecked payload:

Field	Type	Required	Description
entryId	guid	yes
subjectKind	string	yes
subjectId	string	yes
subjectVersion	string	yes
withKind	string	yes
withId	string	yes
result	enum:Compatibility	yes

Command	Handled by	Result events	Summary
DiscoverTemplates	TemplateVersion	TemplateVersionDiscovered, LibraryVersionDiscovered
PublishTemplateVersion	TemplateVersion	—

Event	Producer	Handler	Purpose
AssetReleasePublished	AgentRegistryService	MarkPublished	Template releases published by Asset Publication.
AssetReleaseDeprecated	AgentRegistryService	MarkDeprecated	Deprecated template releases.
PipelineRunCompleted	PipelineExecutionService	RecordBuildEvidence	Template repository builds are compatibility evidence.
ChunksPublished	KnowledgeIngestionService	RefreshDocs	Template documentation ingested for the catalog's docs links.

Workers and jobs

Worker	Trigger	Output events	Retry	Idempotency key	Summary
Discoverer	schedule 0 */6 * * *	TemplateVersionDiscovered, LibraryVersionDiscovered	fixed	repository + commit	Reads .template.config, project files, switches, pipelines and docs from every template repository (through connectors) and package versions from the feeds; pins manifests by hash.
CompatibilityComputer	event	CompatibilityChecked	fixed	cell + evidence	Computes matrix cells from manifests, package references, build evidence and conformance runs; marks cells Unknown where evidence is missing.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

sequenceDiagram
    participant D as Discoverer (every 6 h)
    participant CX as Azure DevOps / GitHub connector
    participant F as Package feed
    participant T as TemplateRegistryService
    participant CC as CompatibilityComputer
    participant P as PipelineExecutionService
    D->>CX: read template repositories (.template.config, projects, switches, pipelines, docs)
    D->>F: read package versions
    D->>T: pin manifests by hash → TemplateVersionDiscovered, LibraryVersionDiscovered
    P-)T: PipelineRunCompleted (template repository build)
    T->>CC: compute cells with evidence
    CC-)T: CompatibilityChecked (Compatible | Unknown)

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

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Templates:Catalog	DiscoverIntervalHours	int	6	yes	no	Discovery interval.
Templates:Catalog	Runtimes	string[]	[net9.0, net10.0]	yes	no	Runtimes the matrix is computed for.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.templates.versions	updown	{version}	kind, layer, state	Template and library versions by state.
connectsoft.factory.templates.compatibility_unknown	updown	{cell}	subjectKind	Cells without evidence.

Security

Authentication	client-credentials
Scopes	factory.catalog.read (Read the catalog and matrix.); factory.catalog.admin (Discover and publish (Asset maintainer, Platform admin).)
Roles	Requester, AssetMaintainer, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	internal
Max side-effect class	publication
Secrets	—

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
ConnectorRegistryService	grpc	Template repositories and feeds through the Azure DevOps and GitHub connectors.	degrade	yes
AgentRegistryService	grpc	Template release candidates.	fail-fast	yes
RepositoryIntelligenceService	grpc	Dependency graphs of template repositories.	degrade	no

Inbound

Target	Kind	Purpose	Failure mode	Required
GenerationRecipeService	grpc	ResolveManifest and compatibility.	—	yes
AgentRuntimeWorker	grpc	Agents read manifests during generation.	—	yes
StudioBff	sync-http	Catalog views.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Feed unreachable	discovery errors	last pinned manifests stay; new versions are not discovered until the feed is back; cells stay as they were	stale catalog	360

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	module of host · host TemplateCatalogHost
Topologies	saas-default, hybrid, on-prem
Runtime	—; replicas —–—
Ports	—

Current implementation

templates-docs/templates-overview.md and the generated catalog list the templates; the 192-repository inventory of L1 produced model/templates.yaml and model/libraries.yaml. No runtime registry, manifest pinning or matrix exists.

Later capabilities

Template upgrade advisor (deferred row): diff of manifests between versions with migration notes; package upgrade advisor for libraries; conformance runs per template per runtime as scheduled evidence.

Decisions and traceability

Family	Ids
FR	FR-06
FUX	FUX-03
NFR	NFR-13
XL	XL-03, XL-07

Related

• Overview · Template catalog · Library catalog · Compatibility model (June 2026) · RepositoryIntelligenceService

• Template & Library microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map