Skip to content

Template Layering Guide

This document provides a technical guide to ConnectSoft's template layering architecture. It is written for architects and engineers who need to understand how templates are structured, how they reuse code and documentation, and how the build-time and generation-time processes differ.

ConnectSoft avoids copy-pasting and "template inheritance" by splitting responsibilities across three layers: shared libraries, base service template, and specialized templates. This architecture enables maximum reuse while maintaining flexibility and avoiding duplication.

Important

The three-layer model is fundamental to ConnectSoft's template architecture. Understanding this model is essential for working with templates, extending them, or creating new specialized templates.

The Three-Layer Model

ConnectSoft templates are organized into three distinct layers:

flowchart TB
    subgraph Layer1["Layer 1: Shared Libraries"]
        LIB1[ConnectSoft.Extensions.Logging]
        LIB2[ConnectSoft.Extensions.Messaging]
        LIB3[ConnectSoft.Extensions.Persistence]
        LIB4[ConnectSoft.Extensions.Options]
        LIB5[ConnectSoft.Extensions.Metrics]
    end

    subgraph Layer2["Layer 2: Base Service Template"]
        BASE[MicroserviceTemplate.Base<br/>Solution Layout<br/>Bootstrapping<br/>Common Infrastructure]
    end

    subgraph Layer3["Layer 3: Specialized Templates"]
        IDENTITY[Identity Template<br/>+ Identity Domain Logic]
        AUTH[Auth Template<br/>+ Auth Domain Logic]
        AUDIT[Audit Template<br/>+ Audit Domain Logic]
        WORKER[Worker Template<br/>+ Worker Domain Logic]
    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 (ConnectSoft.Extensions.*)

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

Responsibilities: - Observability (logging, tracing, metrics infrastructure) - Messaging (MassTransit, bus conventions) - Persistence (NHibernate, base repositories) - Options/config infrastructure - HTTP clients, retry policies, circuit breakers - Testing utilities and helpers

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

Layer 2: Base Service Template (MicroserviceTemplate.Base)

Purpose: One canonical repository containing the microservice "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 testing infrastructure - Base documentation structure - Base template metadata (/template/template.json)

Characteristics: - Single canonical repository - No domain-specific logic (no Identity/Audit/etc.) - Fully buildable as a normal .NET solution - Used as git submodule by specialized templates

Layer 3: Specialized Templates (Identity, Auth, Audit, Worker, etc.)

Purpose: Each specialized template adds domain-specific functionality on top of the base template.

Responsibilities: - Domain-specific projects (Identity, Auth, Worker, etc.) - Domain-specific tests - Domain-specific documentation - Overlay metadata for template.json and docs

Characteristics: - Each template is its own repository - Includes base as git submodule (base-template/) - Adds domain-specific projects - Fully buildable as normal .NET solution without Factory - Defines overlay metadata for generation-time composition

Build Time vs Generation Time

ConnectSoft distinguishes between two modes of operation:

Build Time (Developer Experience)

Goal: Open solution, hit dotnet build / dotnet test, everything just works.

Characteristics: - Specialized template repo includes base as git submodule - Solution file includes projects from both base and specialized template - Developer works on a real, concrete application - No Factory required to build or test - Documentation references both base docs (via submodule) and specialized docs

Example Structure: 

IdentityBackendTemplate/
├── base-template/              # Git submodule
│   ├── src/
│   │   ├── Host/
│   │   ├── Domain/
│   │   └── Infrastructure/
│   └── tests/
│       └── Base.Testing.Infrastructure/
├── src/
│   ├── Identity.Api/          # References base projects
│   ├── Identity.Domain/       # References base.Domain
│   └── Identity.Infrastructure/
├── tests/
│   └── Identity.AcceptanceTests/  # References Base.Testing.Infrastructure
└── IdentityBackend.sln        # Includes all projects

Generation Time (Factory / Template Packaging)

Goal: Produce a final, flattened project template that the AI Factory or dotnet new uses.

Characteristics: - Start from base template (code + docs + metadata) - Apply one or more overlays (Identity, Worker, etc.) in a recipe - Resolve tokens (ServiceName, Namespace, etc.) - Output flattened template artifact - Push to Azure DevOps / Git / etc. with pipelines/work items

Generation Pipeline:

flowchart TD
    BASE[Base Template<br/>Code + Docs + Metadata]
    OVERLAY1[Identity Overlay<br/>Domain Code + Docs + Metadata]
    OVERLAY2[Worker Overlay<br/>Worker Code + Docs + Metadata]

    RECIPE[Recipe:<br/>base + identity + worker]

    GENERATOR[Template Generator]

    OUTPUT[Final Template Artifact<br/>Flattened Structure]

    BASE --> GENERATOR
    OVERLAY1 --> GENERATOR
    OVERLAY2 --> GENERATOR
    RECIPE --> GENERATOR
    GENERATOR --> OUTPUT

    style BASE fill:#BBDEFB
    style OVERLAY1 fill:#C8E6C9
    style OVERLAY2 fill:#C8E6C9
    style OUTPUT fill:#A5D6A7
Hold "Alt" / "Option" to enable pan & zoom

Submodules at Build Time vs Overlays at Generation Time

Build Time: Git Submodules

What: Base template is included as a git submodule in specialized template repos.

Why: - Enables building specialized templates as normal .NET solutions - Base changes propagate automatically - No duplication of base code

How: 

# In Identity template repo
git submodule add <base-repo-url> base-template

Result: Specialized template repo contains both base and specialized code, fully buildable.

Generation Time: Overlays

What: Overlays are applied on top of base template to create final template artifact.

Why: - Enables composition of multiple overlays (Identity + Worker) - Produces flattened template for dotnet new or Factory - Allows recipe-based template generation

How: 

# Recipe example
templateId: identity-worker-service
displayName: "Identity Backend with Worker"
layers:
  - base: microservice/base
  - overlay: microservice/overlays/identity-backend
  - overlay: microservice/overlays/worker

Result: Final template artifact with all overlays applied, ready for generation.

Multi-Overlay Scenarios (Identity + Worker)

Specialized templates can combine multiple overlays. For example, an Identity Backend template might support both Identity domain logic and Worker functionality.

Overlay Stacking

flowchart TB
    BASE[Base Template]
    IDENTITY[Identity Overlay]
    WORKER[Worker Overlay]

    BASE --> IDENTITY
    IDENTITY --> WORKER
    WORKER --> FINAL[Final Template:<br/>Base + Identity + Worker]

    style BASE fill:#BBDEFB
    style IDENTITY fill:#C8E6C9
    style WORKER fill:#FFF9C4
    style FINAL fill:#A5D6A7
Hold "Alt" / "Option" to enable pan & zoom

Practical Example: Identity Backend Template

Repository Structure

ConnectSoft.IdentityBackendTemplate/
├── .gitmodules                    # Git submodule configuration
├── base-template/                 # Git submodule -> MicroserviceTemplate.Base
│   ├── src/
│   │   ├── Host/
│   │   ├── Domain/
│   │   ├── Application/
│   │   └── Infrastructure/
│   ├── tests/
│   │   └── Base.Testing.Infrastructure/
│   ├── docs/
│   │   ├── overview.md
│   │   └── architecture.md
│   └── template/
│       └── template.json
├── src/
│   ├── Identity.Api/              # Identity-specific API
│   ├── Identity.Domain/           # Identity domain logic
│   ├── Identity.Infrastructure/   # Identity infrastructure
│   └── Identity.Worker/            # Optional: Identity worker
├── tests/
│   ├── Identity.UnitTests/        # Identity unit tests
│   └── Identity.AcceptanceTests/   # Identity acceptance tests
├── docs/
│   ├── identity-overview.md
│   ├── identity-auth-flows.md
│   └── identity-metrics.md
├── template/
│   ├── identity.template.extend.json
│   └── worker.template.extend.json
├── IdentityBackend.sln            # Includes base + identity projects
└── pack-template.ps1              # Script to build final template artifacts

Build Process

  1. Clone Repository: 

    git clone <identity-template-repo>
cd IdentityBackendTemplate
git submodule update --init --recursive

  2. Open Solution: 

    dotnet sln IdentityBackend.sln

  3. Build: 

    dotnet build

  4. Test: 

    dotnet test

Everything works as a normal .NET solution. No Factory required.

Rules and Best Practices

Do's

✅ Use git submodules for base template in specialized templates
✅ Keep base template domain-agnostic - no Identity/Audit/etc. logic
✅ Build specialized templates as normal solutions - they should compile without Factory
✅ Use overlays for generation-time composition - enables recipe-based templates
✅ Reference base docs via submodule at build time
✅ Merge docs physically at generation time

Don'ts

❌ Don't duplicate base code - use submodules instead
❌ Don't put domain logic in base - base is infrastructure only
❌ Don't modify base template.json directly - use extend files
❌ Don't copy base docs - reference via submodule
❌ Don't require Factory to build - templates must build as normal solutions