Skip to content

Template Overlays Specification

This document is the authoritative technical specification for ConnectSoft's overlay system, versioning, and compatibility management. It serves as the contract for both humans and agents working with template overlays, defining the rules, mechanisms, and patterns that govern overlay composition, versioning, and compatibility.

Important

This specification defines the technical contract for overlay system. All overlay implementations, Factory agents, and human developers must adhere to these rules and patterns.

Document Purpose

This specification provides:

  • Complete technical contract for overlay system architecture
  • Overlay application process and composition rules
  • Versioning scheme for base and specialized templates
  • Compatibility management and declaration format
  • Recipe system for template composition
  • Authoritative source for agents and developers

For template architecture details, see Template Architecture Specification. For practical guides, see Template Layering Guide.

Overlay System Architecture

What is an Overlay?

An overlay is a collection of code, documentation, and metadata that extends or modifies a base template. Overlays enable:

  • Domain-specific functionality (Identity, Auth, Audit, Worker)
  • Composition of multiple overlays (Identity + Worker)
  • Reusability of overlay components across templates
  • Flexibility in template generation

Overlay Components:

  1. Code Files - Domain-specific projects, classes, interfaces
  2. Documentation - Domain-specific documentation files
  3. Metadata - Template.json extend files, configuration
  4. Tests - Domain-specific test projects and test cases

Overlay Types

ConnectSoft defines several overlay types:

Domain Overlays:

  • Identity Overlay - User management, authentication, authorization
  • Auth Overlay - OAuth2/OIDC server functionality
  • Audit Overlay - Audit trail and compliance logging
  • Worker Overlay - Background job processing

Feature Overlays:

  • Worker Overlay - Background job processing capabilities
  • Scheduler Overlay - Scheduled task execution
  • API Gateway Overlay - API gateway integration

Infrastructure Overlays: - Observability Overlay - Enhanced observability features - Security Overlay - Additional security features

Overlay Composition Order and Precedence

Overlays are applied in a specific order defined by the recipe:

Composition Rules:

  1. Base is always first - All compositions start with base template
  2. Overlays applied sequentially - Order matters for file patching and token replacement
  3. Later overlays override earlier - Conflicts resolved by last overlay wins
  4. Metadata merged sequentially - template.json extended in order

Precedence Diagram:

flowchart TB
    BASE[Base Template<br/>Priority: 0]
    OVERLAY1[First Overlay<br/>Priority: 1]
    OVERLAY2[Second Overlay<br/>Priority: 2]
    OVERLAY3[Third Overlay<br/>Priority: 3]

    BASE --> OVERLAY1
    OVERLAY1 --> OVERLAY2
    OVERLAY2 --> OVERLAY3
    OVERLAY3 --> FINAL[Final Template<br/>All Overlays Applied]

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

Multi-Overlay Scenarios

Multiple overlays can be composed to create complex templates:

Example: Identity + Worker

  • Base Template (foundation)
  • Identity Overlay (domain logic)
  • Worker Overlay (background jobs)

Example: Auth + Scheduler

  • Base Template (foundation)
  • Auth Overlay (OAuth2/OIDC server)
  • Scheduler Overlay (scheduled tasks)

Stacking Rules:

  1. No circular dependencies - Overlays cannot depend on each other in cycles
  2. Explicit dependencies - Overlays declare dependencies on other overlays
  3. Compatibility checks - All overlays must be compatible with base and each other
  4. Order matters - Overlays applied in recipe order

Overlay Application Process

File Addition

Purpose: Add new files from overlay to final template.

Process:

  1. Overlay defines new files (code, docs, tests)
  2. Files copied to final template structure
  3. Tokens replaced (ServiceName, Namespace, etc.)
  4. File paths adjusted if needed

Example: 

Identity Overlay adds:
- src/Identity.Api/Identity.Api.csproj
- src/Identity.Domain/Identity.Domain.csproj
- src/Identity.Infrastructure/Identity.Infrastructure.csproj
- tests/Identity.UnitTests/Identity.UnitTests.csproj

File Patching

Purpose: Modify existing base files without replacing them entirely.

Mechanisms:

  1. Marker-Based Insertion

    • Base files contain markers (e.g., // #IDENTITY_REGISTRATION)
    • Overlay files define content to insert at markers
    • Content inserted between markers during generation

  2. Patch Files

    • Overlay defines patch files (unified diff format)
    • Patches applied to base files
    • Conflicts detected and resolved

  3. Partial Replacement

    • Overlay defines sections to replace
    • Base file sections replaced with overlay content
    • Rest of base file preserved

Example Marker-Based Insertion:

Base File (Program.cs): 

// ... base code ...

// #IDENTITY_REGISTRATION
// Overlay will insert Identity service registration here
// #END_IDENTITY_REGISTRATION

// ... more base code ...

Identity Overlay File: 

// #IDENTITY_REGISTRATION
builder.Services.AddConnectSoftIdentityInfrastructure(configuration);
// #END_IDENTITY_REGISTRATION

Result: 

// ... base code ...

builder.Services.AddConnectSoftIdentityInfrastructure(configuration);

// ... more base code ...

Token Replacement

Purpose: Replace placeholders with actual values during generation.

Tokens:

  • ServiceName - Name of the generated service
  • RootNamespace - Root namespace for generated code
  • ServiceNameLower - Lowercase service name
  • ServiceNamePascal - PascalCase service name
  • Domain-specific tokens (e.g., IdentityService)

Replacement Process:

  1. All files scanned for token patterns
  2. Tokens replaced with actual values
  3. File names updated if they contain tokens
  4. Project references updated

Example: 

Token: ServiceName
Value: IdentityBackendService

Before: namespace MyCompany.ServiceName.Domain;
After:  namespace MyCompany.IdentityBackendService.Domain;

Documentation Merging

Purpose: Combine base and overlay documentation into final structure.

Process:

  1. Base docs copied to final docs/ directory
  2. Overlay docs copied to final docs/ directory
  3. Cross-references updated
  4. Table of contents merged
  5. Navigation structure updated

Merging Rules:

  • Base docs preserved
  • Overlay docs added
  • Conflicts resolved by overlay wins
  • Cross-references updated to reflect final structure

Metadata Merging

Purpose: Combine base template.json with overlay extend files.

Process:

  1. Load base template.json
  2. Apply overlay extend files in order
  3. Merge according to rules (see Template Architecture Specification)
  4. Validate final template.json
  5. Write merged template.json

Merge Order:

  1. Apply identityOverrides
  2. Apply symbolOverrides
  3. Apply symbolAdds
  4. Apply postActionsAdds
  5. Apply primaryOutputsAdds

Versioning & Compatibility

Base Template Versioning

Scheme: Semantic Versioning (MAJOR.MINOR.PATCH)

Format: MAJOR.MINOR.PATCH (e.g., 1.2.3)

Version Bump Rules:

  • MAJOR - Breaking changes to template structure

    • Changes to required parameters
    • Changes to project structure
    • Changes to extension point interfaces
    • Example: 1.2.3 → 2.0.0

  • MINOR - New features, backward compatible

    • New optional parameters
    • New extension points
    • New base functionality
    • Example: 1.2.3 → 1.3.0

  • PATCH - Bug fixes, backward compatible

    • Bug fixes in base code
    • Documentation updates
    • Minor improvements
    • Example: 1.2.3 → 1.2.4

Version Location:

  • Base template version in template/template.json: 
    {
  "version": "1.2.3",
  "author": "ConnectSoft"
}

Specialized Template Versioning

Scheme: Semantic Versioning (MAJOR.MINOR.PATCH) with base compatibility range

Format: MAJOR.MINOR.PATCH (e.g., 2.1.0)

Version Bump Rules:

  • MAJOR - Breaking changes to overlay structure or base compatibility

    • Changes requiring new base template version
    • Breaking changes to overlay structure
    • Example: 2.1.0 → 3.0.0

  • MINOR - New features, backward compatible

    • New overlay features
    • New parameters
    • Example: 2.1.0 → 2.2.0

  • PATCH - Bug fixes, backward compatible

    • Bug fixes in overlay code
    • Documentation updates
    • Example: 2.1.0 → 2.1.1

Base Compatibility:

  • Specialized templates declare compatible base template versions
  • Example: 2.1.0 compatible with base ^1.5.0 (>=1.5.0 <2.0.0)

Compatibility Declaration Format

Overlays declare compatibility with base template versions using a manifest file.

Overlay Manifest Structure:

{
  "overlayId": "identity-backend",
  "version": "2.1.0",
  "baseCompatibility": {
    "minVersion": "1.5.0",
    "maxVersion": "2.0.0",
    "range": "^1.5.0"
  },
  "dependencies": {
    "overlays": []
  },
  "metadata": {
    "displayName": "Identity Backend Overlay",
    "description": "Identity domain logic overlay",
    "author": "ConnectSoft"
  }
}

Compatibility Range Syntax:

  • ^1.5.0 - Compatible with >=1.5.0 <2.0.0
  • >=1.5.0 <2.0.0 - Explicit range
  • ~1.5.0 - Compatible with >=1.5.0 <1.6.0
  • 1.5.0 - Exact version (not recommended)

Dependencies:

Overlays can depend on other overlays:

{
  "dependencies": {
    "overlays": [
      {
        "overlayId": "worker",
        "version": "^1.0.0"
      }
    ]
  }
}

Compatibility Matrix

A compatibility matrix tracks which overlay versions work with which base versions:

Matrix Format:

Base Version Identity Overlay Auth Overlay Worker Overlay
1.5.0 2.0.0 - 2.1.0 1.0.0 - 1.2.0 1.0.0 - 1.1.0
1.6.0 2.1.0 - 2.2.0 1.1.0 - 1.3.0 1.1.0 - 1.2.0
2.0.0 3.0.0+ 2.0.0+ 2.0.0+

Compatibility Matrix Diagram:

graph TB
    subgraph BaseVersions["Base Template Versions"]
        B1[1.5.0]
        B2[1.6.0]
        B3[2.0.0]
    end

    subgraph IdentityVersions["Identity Overlay Versions"]
        I1[2.0.0]
        I2[2.1.0]
        I3[2.2.0]
        I4[3.0.0]
    end

    B1 -->|Compatible| I1
    B1 -->|Compatible| I2
    B2 -->|Compatible| I2
    B2 -->|Compatible| I3
    B3 -->|Compatible| I4

    style B1 fill:#BBDEFB
    style B2 fill:#BBDEFB
    style B3 fill:#BBDEFB
    style I1 fill:#C8E6C9
    style I2 fill:#C8E6C9
    style I3 fill:#C8E6C9
    style I4 fill:#C8E6C9
Hold "Alt" / "Option" to enable pan & zoom

Breaking Change Handling

Breaking Changes Defined:

  1. Base Template Breaking Changes:

    • Removal of required parameters
    • Changes to extension point interfaces
    • Changes to project structure
    • Changes to required post-actions

  2. Overlay Breaking Changes:

    • Changes requiring new base template version
    • Removal of overlay parameters
    • Changes to overlay structure

Breaking Change Process:

  1. Identify Breaking Change - Document what breaks
  2. Bump MAJOR Version - Increment MAJOR version number
  3. Update Compatibility - Update compatibility declarations
  4. Migration Guide - Create migration guide for users
  5. Communication - Notify users of breaking changes

Migration Strategies:

  1. Gradual Migration - Support both old and new versions temporarily
  2. Automated Migration - Provide migration scripts/tools
  3. Documentation - Clear migration guides
  4. Deprecation Period - Deprecate old versions before removal

Version Bump Procedures

When to Bump Base Template Version

MAJOR Bump:

  • Breaking changes to template structure
  • Changes to required parameters
  • Changes to extension point interfaces
  • Changes to project structure

MINOR Bump:

  • New optional parameters
  • New extension points
  • New base functionality
  • New post-actions

PATCH Bump:

  • Bug fixes
  • Documentation updates
  • Minor improvements

When to Bump Specialized Template Version

MAJOR Bump:

  • Breaking changes to overlay structure
  • Changes requiring new base template version
  • Removal of overlay parameters

MINOR Bump:

  • New overlay features
  • New overlay parameters
  • New overlay functionality

PATCH Bump:

  • Bug fixes in overlay
  • Documentation updates
  • Minor improvements

How to Update Compatibility Declarations

Process:

  1. Determine Base Compatibility

    • Test overlay with base template versions
    • Identify minimum and maximum compatible versions
    • Document any breaking changes

  2. Update Overlay Manifest

    • Update baseCompatibility.range
    • Update baseCompatibility.minVersion and maxVersion
    • Update overlay version if needed

  3. Update Compatibility Matrix

    • Add new overlay version to matrix
    • Update compatibility ranges
    • Document any breaking changes

  4. Test Compatibility

    • Test overlay with all compatible base versions
    • Verify overlay application process
    • Verify final template generation

Testing Compatibility After Version Bumps

Test Process:

  1. Unit Tests - Test overlay application with base versions
  2. Integration Tests - Test full template generation
  3. Compatibility Tests - Test with all compatible base versions
  4. Regression Tests - Ensure no regressions

Test Matrix:

Base Version Overlay Version Test Status
1.5.0 2.1.0 ✅ Pass
1.6.0 2.1.0 ✅ Pass
2.0.0 2.1.0 ❌ Fail

Communication of Breaking Changes

Communication Channels:

  1. Release Notes - Document breaking changes in release notes
  2. Migration Guides - Provide step-by-step migration guides
  3. Deprecation Warnings - Warn users before breaking changes
  4. Documentation Updates - Update all relevant documentation

Breaking Change Notice Format:

## Breaking Changes in v2.0.0

### Base Template v2.0.0

**Breaking:** Removed `UseLegacyMessaging` parameter
- **Impact:** Templates using `UseLegacyMessaging=true` will fail
- **Migration:** Use `MessagingType=Legacy` instead
- **Deprecation:** Parameter deprecated in v1.9.0

**Breaking:** Changed `IMetricsFeature` interface
- **Impact:** Custom metrics implementations need update
- **Migration:** See [Migration Guide](migration-guide.md)

Recipe System

Recipe File Format

Recipes define how to compose base template with overlays.

YAML Format:

# Recipe: identity-worker-service.yaml
templateId: identity-worker-service
displayName: "Identity Backend with Worker"
version: "1.0.0"
description: "Identity backend service with background job processing"

layers:
  - base:
      templateId: microservice-base
      version: "^1.5.0"

  - overlay:
      overlayId: identity-backend
      version: "^2.1.0"

  - overlay:
      overlayId: worker
      version: "^1.0.0"

metadata:
  tags:
    - identity
    - worker
    - backend
  classifications:
    - ConnectSoft
    - Microservice
    - Identity
    - Worker

JSON Format:

{
  "templateId": "identity-worker-service",
  "displayName": "Identity Backend with Worker",
  "version": "1.0.0",
  "description": "Identity backend service with background job processing",
  "layers": [
    {
      "base": {
        "templateId": "microservice-base",
        "version": "^1.5.0"
      }
    },
    {
      "overlay": {
        "overlayId": "identity-backend",
        "version": "^2.1.0"
      }
    },
    {
      "overlay": {
        "overlayId": "worker",
        "version": "^1.0.0"
      }
    }
  ],
  "metadata": {
    "tags": ["identity", "worker", "backend"],
    "classifications": ["ConnectSoft", "Microservice", "Identity", "Worker"]
  }
}

Recipe Composition Rules

Rules:

  1. Base is always first - Recipe must start with base layer
  2. Overlays in order - Overlays applied in recipe order
  3. Version compatibility - All layers must be compatible
  4. Dependency resolution - Overlay dependencies resolved automatically
  5. Validation - Recipe validated before execution

Validation Rules:

  • Base template version must exist
  • All overlay versions must exist
  • All versions must be compatible
  • No circular dependencies
  • All required dependencies present

Recipe Validation

Validation Process:

  1. Parse Recipe - Validate YAML/JSON syntax
  2. Check Base - Verify base template exists and version compatible
  3. Check Overlays - Verify all overlays exist and versions compatible
  4. Check Dependencies - Verify overlay dependencies resolved
  5. Check Compatibility - Verify all layers compatible with each other
  6. Check Circular Dependencies - Verify no circular dependencies

Validation Errors:

  • Base template not found
  • Overlay not found
  • Version incompatibility
  • Missing dependencies
  • Circular dependencies

Recipe Execution Order

Execution Process:

  1. Load Base Template - Load base template code, docs, metadata
  2. Resolve Dependencies - Resolve all overlay dependencies
  3. Apply Overlays - Apply overlays in recipe order:
    • Apply Identity overlay
    • Apply Worker overlay
  4. Resolve Tokens - Replace all tokens with actual values
  5. Validate Final Template - Validate final template structure
  6. Output Final Template - Write final template artifact

Execution Order Diagram:

flowchart TD
    START[Start Recipe Execution]
    LOADBASE[Load Base Template<br/>Code + Docs + Metadata]
    RESOLVE[Resolve Dependencies]
    APPLY1[Apply Identity Overlay]
    APPLY2[Apply Worker Overlay]
    RESOLVETOKENS[Resolve Tokens<br/>ServiceName, Namespace, etc.]
    VALIDATE[Validate Final Template]
    OUTPUT[Output Final Template Artifact]

    START --> LOADBASE
    LOADBASE --> RESOLVE
    RESOLVE --> APPLY1
    APPLY1 --> APPLY2
    APPLY2 --> RESOLVETOKENS
    RESOLVETOKENS --> VALIDATE
    VALIDATE --> OUTPUT

    style START fill:#E3F2FD
    style LOADBASE fill:#BBDEFB
    style APPLY1 fill:#C8E6C9
    style APPLY2 fill:#FFF9C4
    style OUTPUT fill:#A5D6A7
Hold "Alt" / "Option" to enable pan & zoom

Generation-Time Composition Flow

The complete flow from base template to final template artifact:

flowchart TB
    subgraph Input["Input"]
        BASE[Base Template<br/>v1.5.0]
        RECIPE[Recipe File<br/>identity-worker-service.yaml]
        OVERLAY1[Identity Overlay<br/>v2.1.0]
        OVERLAY2[Worker Overlay<br/>v1.0.0]
    end

    subgraph Process["Composition Process"]
        VALIDATE[Validate Recipe<br/>& Compatibility]
        LOAD[Load Base Template]
        APPLY1[Apply Identity Overlay]
        APPLY2[Apply Worker Overlay]
        MERGE[Merge Metadata]
        REPLACE[Replace Tokens]
    end

    subgraph Output["Output"]
        FINAL[Final Template Artifact<br/>Ready for dotnet new]
    end

    BASE --> VALIDATE
    RECIPE --> VALIDATE
    OVERLAY1 --> VALIDATE
    OVERLAY2 --> VALIDATE

    VALIDATE --> LOAD
    LOAD --> APPLY1
    APPLY1 --> APPLY2
    APPLY2 --> MERGE
    MERGE --> REPLACE
    REPLACE --> FINAL

    style Input fill:#E3F2FD
    style Process fill:#FFE0B2
    style Output fill:#A5D6A7
Hold "Alt" / "Option" to enable pan & zoom