Template Architecture Implementation

This document describes how the ConnectSoft AI Software Factory implements the template architecture, including template composition, recipe system, version resolution, and agent integration. It focuses on Factory-specific implementation details and workflows.

Overview

The Factory implements a sophisticated template composition system that enables:

• Base template + overlay composition - Combining base templates with specialized overlays
• Recipe-based generation - Defining multi-overlay compositions via recipes
• Agent-driven selection - Agents automatically discover and compose templates
• Version resolution - Automatic compatibility checking and version resolution
• Token replacement - Dynamic parameter injection during generation

Factory Template Composition Engine

Composition Flow

The Factory's template composition engine orchestrates the process of combining base templates with overlays:

flowchart TD
    START[Agent Requests Template Generation]
    BLUEPRINT[Microservice Blueprint]
    CATALOG[Template Catalog Domain]
    RESOLVE[Resolve Base Template]
    RECIPE[Load or Generate Recipe]
    OVERLAYS[Resolve Overlays]
    COMPOSE[Compose Template]
    TOKENS[Replace Tokens]
    VALIDATE[Validate Final Template]
    OUTPUT[Output Generated Service]

    START --> BLUEPRINT
    BLUEPRINT --> CATALOG
    CATALOG --> RESOLVE
    RESOLVE --> RECIPE
    RECIPE --> OVERLAYS
    OVERLAYS --> COMPOSE
    COMPOSE --> TOKENS
    TOKENS --> VALIDATE
    VALIDATE --> OUTPUT

    style START fill:#E3F2FD
    style CATALOG fill:#BBDEFB
    style COMPOSE fill:#C8E6C9
    style OUTPUT fill:#A5D6A7

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

Template Catalog Domain Integration

The Template Catalog domain manages base templates and overlays:

Base Template Management:

• Stores base template artifacts (code, docs, metadata)
• Tracks base template versions
• Provides base template resolution API
• Validates base template structure

Overlay Management:

• Stores overlay artifacts (code deltas, metadata extensions)
• Tracks overlay versions and compatibility ranges
• Provides overlay resolution API
• Validates overlay structure and dependencies

Compatibility Checking:

• Validates base template + overlay compatibility
• Checks version ranges against compatibility declarations
• Resolves overlay dependencies
• Detects circular dependencies

Recipe System Implementation

The Factory implements a recipe-based system for defining template compositions:

Recipe Storage:

• Recipes stored in Template Catalog domain
• Recipes can be predefined or generated dynamically
• Recipes include base template reference and overlay list
• Recipes include parameter defaults and metadata

Recipe Execution:

1. Load Base Template - Fetch base template artifact from catalog
2. Resolve Overlays - Fetch all overlay artifacts in recipe order
3. Validate Compatibility - Check all versions are compatible
4. Apply Overlays - Sequentially apply overlays to base
5. Merge Metadata - Combine template.json files
6. Replace Tokens - Apply parameter values
7. Validate Output - Ensure final template is valid

Recipe Example:

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

Agent-Driven Template Selection

Template Discovery

Agents discover templates through the Template Catalog domain:

Discovery Process:

1. Agent queries Template Catalog with requirements
2. Template Catalog returns matching templates
3. Agent evaluates templates based on blueprint requirements
4. Agent selects best matching template or recipe

Query Parameters:

• Template type (microservice, library, gateway)
• Required features (messaging, persistence, observability)
• Domain tags (identity, audit, worker)
• Compatibility requirements (.NET version, cloud platform)

Agent Template Selection Workflow

sequenceDiagram
    participant Agent as Microservice Generator Agent
    participant Catalog as Template Catalog Domain
    participant Blueprint as Microservice Blueprint
    participant Recipe as Recipe System

    Agent->>Blueprint: Read Blueprint Requirements
    Blueprint-->>Agent: Requirements (domain, features, etc.)
    Agent->>Catalog: Query Templates (type=microservice, tags=identity)
    Catalog-->>Agent: Matching Templates & Recipes
    Agent->>Agent: Evaluate Templates
    Agent->>Recipe: Select Recipe (identity-worker-service)
    Recipe->>Catalog: Resolve Base + Overlays
    Catalog-->>Recipe: Base Template + Overlays
    Recipe-->>Agent: Composed Template Artifact
    Agent->>Agent: Apply Blueprint Parameters
    Agent->>Agent: Generate Service Code

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

Template Parameter Resolution

Agents resolve template parameters from multiple sources:

Parameter Sources:

1. Blueprint - Primary source (service name, domain, features)
2. Recipe Defaults - Recipe-defined parameter defaults
3. Template Defaults - Base template parameter defaults
4. Agent Configuration - Agent-specific configuration

Resolution Order:

1. Blueprint parameters (highest priority)
2. Recipe parameter overrides
3. Template parameter defaults
4. Agent configuration defaults

Integration with Microservice Generator Agent

Agent Workflow

The Microservice Generator Agent integrates with the template composition system:

Workflow Steps:

1. Receive Blueprint - Agent receives microservice blueprint
2. Query Template Catalog - Agent queries for matching templates
3. Select Recipe - Agent selects or generates recipe
4. Resolve Components - Agent resolves base template and overlays
5. Compose Template - Agent composes final template
6. Apply Parameters - Agent applies blueprint parameters
7. Generate Code - Agent generates service code from template

Blueprint to Template Mapping

The agent maps blueprint requirements to template parameters:

Mapping Examples:

• blueprint.persistence: NHibernate → PersistenceType: NHibernate
• blueprint.messaging: MassTransit → MessagingType: MassTransit
• blueprint.domain: Identity → Select Identity overlay
• blueprint.features: [Worker] → Add Worker overlay

Overlay Selection Logic

The agent selects overlays based on blueprint requirements:

Selection Rules:

• Domain overlays selected based on blueprint domain
• Feature overlays selected based on blueprint features
• Infrastructure overlays selected based on deployment requirements
• Compatibility validated before selection

Template Version Resolution

Version Resolution Process

The Factory resolves template versions automatically:

Resolution Steps:

1. Parse Version Requirements - Extract version ranges from recipe
2. Query Template Catalog - Find available versions
3. Filter Compatible Versions - Apply compatibility rules
4. Select Latest Compatible - Choose latest compatible version
5. Validate Dependencies - Ensure all dependencies compatible

Compatibility Checking

The Factory validates compatibility before composition:

Compatibility Checks:

• Base template version exists
• Overlay versions exist
• Base + overlay compatibility ranges match
• Overlay dependencies resolved
• No circular dependencies

Compatibility Matrix:

• Template Catalog maintains compatibility matrix
• Matrix tracks base version ↔ overlay version compatibility
• Matrix updated when new versions published
• Matrix used for automatic version resolution

Overlay Application Process in Factory

File Operations

The Factory applies overlays through file operations:

Add Operations:

• New files from overlay added to final template
• File paths adjusted for final structure
• Tokens replaced in file names and content

Patch Operations:

• Base files modified via marker-based insertion
• Patches applied to base files
• Conflicts detected and resolved

Merge Operations:

• Documentation files merged
• Metadata files (template.json) merged
• Configuration files merged

Token Replacement Pipeline

The Factory replaces tokens during generation:

Token Sources:

• Blueprint parameters
• Recipe parameters
• Template defaults
• Agent configuration

Replacement Process:

1. Extract all tokens from template files
2. Resolve token values from parameter sources
3. Replace tokens in file names
4. Replace tokens in file content
5. Validate all tokens replaced

Template Catalog Domain - Overlay Management

Overlay Storage

The Template Catalog domain stores overlays:

Storage Structure:

• Overlay artifacts (code, docs, metadata)
• Overlay metadata (version, compatibility, dependencies)
• Overlay manifest (overlay.json)
• Overlay extend files (template.extend.json)

Overlay Resolution

The Template Catalog resolves overlays:

Resolution Process:

1. Query overlay by ID and version range
2. Load overlay artifact
3. Load overlay metadata
4. Validate overlay structure
5. Return overlay to composition engine

Dependency Resolution

The Template Catalog resolves overlay dependencies:

Dependency Resolution:

1. Parse overlay dependencies from manifest
2. Resolve each dependency recursively
3. Check for circular dependencies
4. Return dependency tree
5. Validate all dependencies compatible

Recipe System Implementation

Recipe Storage

Recipes are stored in the Template Catalog domain:

Storage Structure:

• Recipe metadata (ID, version, description)
• Recipe layers (base + overlays)
• Recipe parameters (defaults, overrides)
• Recipe validation rules

Recipe Execution

The Factory executes recipes:

Execution Steps:

1. Load Recipe - Fetch recipe from catalog
2. Validate Recipe - Check recipe structure and compatibility
3. Resolve Base - Load base template artifact
4. Resolve Overlays - Load all overlay artifacts
5. Apply Composition - Apply overlays in order
6. Merge Metadata - Combine template.json files
7. Replace Tokens - Apply parameter values
8. Validate Output - Ensure final template valid

Recipe Generation

Agents can generate recipes dynamically:

Generation Process:

1. Agent analyzes blueprint requirements
2. Agent queries Template Catalog for components
3. Agent selects base template
4. Agent selects overlays based on requirements
5. Agent generates recipe structure
6. Agent validates recipe
7. Agent stores recipe in catalog (optional)

Integration Points

Template Catalog API

The Template Catalog domain provides APIs for:

• Template Discovery - Query templates by type, tags, features
• Template Resolution - Resolve template by ID and version
• Overlay Resolution - Resolve overlay by ID and version
• Recipe Management - Store, retrieve, validate recipes
• Compatibility Checking - Validate version compatibility

Agent Integration

Agents integrate with template system through:

• Template Catalog Client - Query and resolve templates
• Recipe Client - Load and execute recipes
• Composition Engine - Compose templates from components
• Token Replacement - Apply parameters to templates

Event Integration

Template composition emits events:

• TemplateCompositionStarted - Composition process started
• TemplateCompositionCompleted - Composition process completed
• TemplateCompositionFailed - Composition process failed
• OverlayApplied - Overlay applied to template
• TokenReplacementCompleted - Token replacement completed

Related Documents

• Template Catalog Domain - Template Catalog domain specification
• Microservice Generator Agent - Agent specification
• Agent Template Integration Guide - Agent integration details