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.*<br/>NuGet Packages]
    end

    subgraph Layer2["Layer 2: Base Templates"]
        BASE[MicroserviceTemplate.Base<br/>LibraryTemplate.Base<br/>APILibraryTemplate.Base]
    end

    subgraph Layer3["Layer 3: Specialized Templates"]
        IDENTITY[Identity Template<br/>+ Identity Domain]
        AUTH[Auth Template<br/>+ Auth Domain]
        WORKER[Worker Template<br/>+ Worker Domain]
    end

    Layer1 -->|NuGet Packages| Layer2
    Layer1 -->|NuGet Packages| Layer3
    Layer2 -->|Git Submodule| Layer3

    style Layer1 fill:#E3F2FD
    style Layer2 fill:#BBDEFB
    style Layer3 fill:#90CAF9

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

Layer 1: Shared Libraries¶

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

Responsibilities:

Observability (logging, tracing, metrics)
Messaging (MassTransit, event bus)
Persistence (NHibernate, repositories)
Options and configuration
HTTP clients and resilience
Testing utilities

Characteristics:

Delivered as NuGet packages
Used by all templates and services
Versioned independently
No domain-specific logic

Example Libraries:

ConnectSoft.Extensions.Logging - Structured logging, correlation IDs
ConnectSoft.Extensions.Messaging - MassTransit abstractions
ConnectSoft.Extensions.Persistence - NHibernate base repositories
ConnectSoft.Extensions.Options - Configuration infrastructure
ConnectSoft.Extensions.Metrics - OpenTelemetry metrics

Layer 2: Base Templates¶

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

Responsibilities:

Solution layout (Host, Domain, Application, Infrastructure, Tests)
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
Provides foundation for all specialized templates

Base Templates:

MicroserviceTemplate.Base - Base microservice structure
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., Identity.Api, Identity.Domain)
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

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]

    style BASE fill:#E3F2FD
    style OVERLAY1 fill:#BBDEFB
    style OVERLAY2 fill:#90CAF9
    style FINAL fill:#C8E6C9

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¶

MicroserviceTemplate.Base/
├── src/
│   ├── Host/
│   ├── Domain/
│   ├── Application/
│   └── Infrastructure/
├── tests/
│   └── Base.Testing.Infrastructure/
├── docs/
│   ├── overview.md
│   └── architecture.md
└── template/
    ├── template.json
    ├── ide.host.json
    └── dotnetcli.host.json

Specialized Template Structure¶

IdentityBackendTemplate/
├── .gitmodules              # Git submodule for base template
├── base-template/           # Git submodule → MicroserviceTemplate.Base
│   ├── src/
│   ├── tests/
│   └── docs/
├── src/                     # Identity-specific code
│   ├── Identity.Api/
│   ├── Identity.Domain/
│   └── Identity.Infrastructure/
├── tests/                   # Identity-specific tests
│   ├── Identity.UnitTests/
│   └── Identity.AcceptanceTests/
├── docs/                    # Identity-specific documentation
│   ├── identity-overview.md
│   └── identity-auth-flows.md
└── template/
    ├── identity.template.extend.json  # Extends base template.json
    ├── ide.host.json
    └── dotnetcli.host.json

Template Inheritance¶

JSON/CLI Inheritance¶

Templates use JSON inheritance to extend base template metadata:

Base Template (template.json):

{
  "identity": "ConnectSoft.MicroserviceTemplate.Base",
  "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)¶

Template Composition¶

Overlay Composition¶

Multi-Overlay Composition¶

Composition Process¶

Template Structure¶

Base Template Structure¶

Specialized Template Structure¶

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¶