Template Architecture¶

This document provides a comprehensive guide to ConnectSoft's template architecture, including the three-layer model, template composition, overlays, and extensibility patterns. It serves as the foundation for understanding how templates are structured, how they compose, and how to extend them.

Overview¶

ConnectSoft templates follow a sophisticated three-layer architecture that enables maximum reuse, consistency, and flexibility. This architecture avoids code duplication while maintaining the ability to build and test templates independently.

Three-Layer Architecture¶

ConnectSoft templates are organized into three distinct layers:

flowchart TB
    subgraph Layer1["Layer 1: Shared Libraries"]
        LIB1[ConnectSoft.Extensions NuGet packages]
    end

    subgraph Layer2["Layer 2: Base Templates"]
        BASE[ConnectSoft.BaseTemplate and other base repos]
    end

    subgraph Layer3["Layer 3: Specialized Templates"]
        IDENTITY[ConnectSoft.IdentityTemplate and overlays]
        WORKER[Worker and other domain templates]
    end

    Layer1 -->|Central Package Management| Layer2
    Layer1 -->|Central Package Management| Layer3
    Layer2 -->|Git submodule base-template| Layer3

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

Layer 1: Shared Libraries¶

Purpose: All generic, cross-cutting infrastructure delivered as NuGet packages.

Catalog: ConnectSoft.Extensions catalog (packages and MSBuild conditions as pinned in ConnectSoft.BaseTemplate Directory.Packages.props).

Characteristics:

Delivered as NuGet packages
Used by all templates and services
Versioned in template Directory.Packages.props
No domain-specific logic

Layer 2: Base Templates¶

Purpose: Canonical repository containing the service "kernel" - all common structure and bootstrapping without domain-specific logic.

Responsibilities:

Solution layout: ConnectSoft.BaseTemplate.* model projects and host (see ConnectSoft.BaseTemplate.slnx)
Program/Host bootstrapping
Common health checks, resilience patterns
Base CI/CD pipelines
Base documentation structure
Canonical template.json metadata

Characteristics:

Domain-agnostic
Fully buildable as normal .NET solution
Used as Git submodule by specialized templates (microservice family uses the base-template path → ConnectSoft.BaseTemplate repository)
Provides foundation for all specialized templates

Base Templates:

ConnectSoft.BaseTemplate (primary microservice base; submodule folder base-template/) — .NET 10, canonical host and solution layout
LibraryTemplate.Base - Base library structure
APILibraryTemplate.Base - Base API library structure

Layer 3: Specialized Templates (Overlays)¶

Purpose: Domain-specific templates that add functionality on top of base templates.

Responsibilities:

Domain-specific projects (e.g., ConnectSoft.IdentityTemplate.DomainModel, ConnectSoft.IdentityTemplate.ServiceModel.RestApi)
Domain-specific tests
Domain-specific documentation
Domain-specific configuration

Characteristics:

Include base template as Git submodule
Add domain logic without modifying base
Can be composed with other overlays
Fully buildable independently

Example Overlays:

Identity Backend Template
Authorization Server Template
Audit Template
Worker Template
API Gateway Template, Microservice Template, Bot Framework template, Health Checks Aggregator (each extends ConnectSoft.BaseTemplate via the same base-template submodule pattern)

Dependency injection layering (ASP.NET Core templates)¶

Templates that host ASP.NET Core (Identity, Authorization Server, Bot Framework, Health Checks Aggregator, API Gateway, Microservice Template) compose DI in three layers:

ApplicationModelRegistrationBase (NuGet) — shared application-model registration from ConnectSoft packages
MicroserviceRegistrationBase (base-template submodule) — microservice kernel registration from ConnectSoft.BaseTemplate
Template-specific registration — e.g. identity, gateway, or bot-specific *Registration* types in the overlay repo

The Worker Template does not use an ASP.NET Core web host; it uses a simpler worker-oriented DI setup without this three-layer web stack.

Template Composition¶

Overlay Composition¶

Specialized templates act as "overlays" that are applied to base templates at generation time:

flowchart LR
    BASE[Base Template] --> COMPOSE[Composition Engine]
    OVERLAY1[Identity Overlay] --> COMPOSE
    OVERLAY2[Worker Overlay] --> COMPOSE
    COMPOSE --> FINAL[Final Composed Template]

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

Multi-Overlay Composition¶

Multiple overlays can be composed to create highly specialized services:

Example: Identity Backend with Worker functionality

Base Template (microservice structure)
    + Identity Overlay (identity domain logic)
    + Worker Overlay (worker functionality)
    = Identity Worker Service

Or formatted as a composition formula:

Identity Worker Service = Base Template + Identity Overlay + Worker Overlay

Where:

Base Template provides the microservice structure
Identity Overlay adds identity domain logic
Worker Overlay adds worker functionality

Composition Process¶

Load Base Template - Fetch base template artifact
Resolve Overlays - Fetch all overlay artifacts
Validate Compatibility - Check version compatibility
Apply Overlays - Sequentially apply overlays
Merge Metadata - Combine template.json files
Replace Tokens - Apply parameter values
Validate Output - Ensure final template is valid

Template Structure¶

Base Template Structure¶

ConnectSoft.BaseTemplate/
├── src/ConnectSoft.BaseTemplate.*/
├── tests/
├── Directory.Packages.props
├── ConnectSoft.BaseTemplate.slnx
└── template/
    ├── template.json
    ├── ide.host.json
    └── dotnetcli.host.json

Specialized Template Structure (ConnectSoft.IdentityTemplate example)¶

ConnectSoft.IdentityTemplate/
├── base-template/
├── ConnectSoft.IdentityTemplate.slnx
├── Directory.Build.props
├── Directory.Packages.props
├── ConnectSoft.IdentityTemplate.*/
├── ConnectSoft.IdentityTemplate.*Tests/
├── Docs/
└── template/
    ├── identity.template.extend.json
    └── dotnetcli.host.json

Template Inheritance¶

JSON/CLI Inheritance¶

Templates use JSON inheritance to extend base template metadata:

Base Template (template.json):

{
  "identity": "ConnectSoft.BaseTemplate",
  "name": "Microservice Base Template",
  "parameters": {
    "ServiceName": {
      "type": "text",
      "default": "MyService"
    }
  }
}

Specialized Template (identity.template.extend.json):

{
  "extends": "base-template/template/template.json",
  "identity": "ConnectSoft.IdentityBackendTemplate",
  "name": "Identity Backend Template",
  "parameters": {
    "ServiceName": {
      "default": "IdentityService"
    },
    "UseOAuth2": {
      "type": "bool",
      "default": true
    }
  }
}

Build-Time vs Generation-Time¶

Build-Time:

Templates are normal .NET solutions
Can be built, tested, and debugged independently
Base template included as Git submodule
Full IDE support

Generation-Time:

Templates are composed from base + overlays
Overlays applied to base template
Tokens replaced with actual values
Final template generated for use

Recipe System¶

Recipe Definition¶

Recipes define multi-overlay compositions:

recipeId: identity-worker-service
version: 1.0.0
baseTemplate:
  templateId: microservice-base
  version: "^1.5.0"
overlays:
  - overlayId: identity-backend
    version: "^2.1.0"
  - overlayId: worker
    version: "^1.0.0"
parameters:
  ServiceName: "IdentityWorkerService"
  RootNamespace: "MyCompany.IdentityWorker"
  UseMassTransit: true
  UseNHibernate: true

Recipe Execution¶

Load base template
Resolve all overlays
Validate compatibility
Apply overlays in order
Merge metadata
Replace tokens
Validate output

Template Extensibility¶

Creating New Overlays¶

To create a new specialized template:

Create Repository - New repository for specialized template
Add Base Submodule - Include base template as Git submodule
Add Domain Code - Add domain-specific projects
Extend Metadata - Create template.extend.json
Add Documentation - Document domain-specific features
Register in Catalog - Register template in Template Catalog

Extending Base Templates¶

Base templates are extended through:

Git Submodules - Base template included as submodule
JSON Extension - template.extend.json extends base metadata
File Overlays - Domain files added alongside base files
Marker-Based Patching - Base files modified via markers

Template Catalog Integration¶

Template Registration¶

Templates are registered in the Template Catalog domain:

Base Templates - Registered with version and metadata
Overlays - Registered with compatibility ranges
Recipes - Registered with composition definitions

Template Discovery¶

Agents discover templates through the Template Catalog:

Query by type (microservice, library, gateway)
Query by features (messaging, persistence, observability)
Query by domain tags (identity, audit, worker)
Query by compatibility (.NET version, cloud platform)

Best Practices¶

Template Design¶

Keep Base Templates Domain-Agnostic - Base templates should not contain domain logic
Use Overlays for Domain Logic - Domain-specific code belongs in overlays
Maintain Compatibility - Track and maintain version compatibility
Document Extensions - Document all template extensions and overlays

Composition¶

Validate Before Composition - Always validate compatibility before composing
Order Matters - Apply overlays in correct order
Handle Conflicts - Detect and resolve file conflicts
Test Compositions - Test composed templates thoroughly

Versioning¶

Semantic Versioning - Use semantic versioning for templates
Compatibility Ranges - Declare compatibility ranges clearly
Breaking Changes - Document breaking changes explicitly
Migration Guides - Provide migration guides for major versions

Template Architecture Implementation - Factory-specific implementation
Template Catalog - Template Catalog domain
Templates Overview - Templates overview
Microservice Template - Microservice template details
Template Integration Guide - Agent integration

External References¶

For detailed technical specifications, see the ConnectSoft Documentation repository:

Template Architecture Specification - Complete technical specification
Template Layering and Reuse - Layering guide
Template Overlays Specification - Overlays specification
Template Metadata Composition - Metadata composition

Note

These detailed specifications are available in the ConnectSoft.Documentation repository under Docs/starters/. They provide comprehensive technical details on template architecture, layering, overlays, and metadata composition.

Template Architecture¶

Overview¶

Three-Layer Architecture¶

Layer 1: Shared Libraries¶

Layer 2: Base Templates¶

Layer 3: Specialized Templates (Overlays)¶

Dependency injection layering (ASP.NET Core templates)¶

Template Composition¶

Overlay Composition¶

Multi-Overlay Composition¶

Composition Process¶

Template Structure¶

Base Template Structure¶

Specialized Template Structure (ConnectSoft.IdentityTemplate example)¶

Template Inheritance¶

JSON/CLI Inheritance¶

Build-Time vs Generation-Time¶

Recipe System¶

Recipe Definition¶

Recipe Execution¶

Template Extensibility¶

Creating New Overlays¶

Extending Base Templates¶

Template Catalog Integration¶

Template Registration¶

Template Discovery¶

Best Practices¶

Template Design¶

Composition¶

Versioning¶

Related Documents¶

External References¶