Skip to content

Template Architecture Overview

This document provides a business-oriented overview of ConnectSoft's template architecture. It is written for product leads, architects, and stakeholders who need to understand the value proposition and high-level approach without diving into technical implementation details.

ConnectSoft's template architecture enables rapid, consistent, and maintainable microservice development through a three-layer model that eliminates duplication while maintaining flexibility.

Executive Summary

ConnectSoft templates are organized into three layers: shared libraries, base service template, and specialized templates. This architecture ensures that common infrastructure is written once and reused everywhere, while specialized templates add domain-specific functionality without modifying the base. The result is faster development, consistent quality, and easier maintenance across all ConnectSoft-generated systems.

The architecture distinguishes between build time (when developers work on templates as normal .NET solutions) and generation time (when the Factory composes final templates from base + overlays). This dual-mode approach provides excellent developer experience while enabling flexible template composition.

Why This Matters

Business Value

ConnectSoft's template architecture delivers significant business value:

  • Faster Time-to-Market - Developers don't rebuild common infrastructure from scratch
  • Consistent Quality - All services follow the same proven patterns
  • Reduced Maintenance - Changes to base infrastructure benefit all templates automatically
  • Lower Risk - Proven patterns reduce bugs and architectural mistakes
  • Scalability - New specialized templates can be created quickly by adding domain logic to base

Technical Benefits

  • Zero Duplication - Common code exists in one place only
  • Buildable Templates - All templates work as normal .NET solutions
  • Automatic Propagation - Base improvements benefit all templates
  • Domain Flexibility - Specialized templates add domain logic without modifying base
  • Recipe Support - Templates can be composed (Identity + Worker, etc.)

The Three-Layer Model

ConnectSoft templates are organized into three distinct layers:

flowchart TB
    subgraph Layer1["Layer 1: Shared Libraries"]
        LIB[ConnectSoft.Extensions.*<br/>NuGet Packages<br/>Observability, Messaging,<br/>Persistence, Options]
    end

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

    subgraph Layer3["Layer 3: Specialized Templates"]
        IDENTITY[Identity Template]
        AUTH[Auth Template]
        AUDIT[Audit Template]
        WORKER[Worker Template]
    end

    Layer1 -->|Used by| Layer2
    Layer1 -->|Used by| Layer3
    Layer2 -->|Included as<br/>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

What: Generic, cross-cutting infrastructure delivered as NuGet packages.

Examples: - Logging and observability - Messaging (MassTransit) - Persistence (NHibernate) - Configuration management - Testing utilities

Value: Written once, used everywhere. Versioned independently, updated across all services.

Layer 2: Base Service Template

What: Canonical microservice "kernel" - all common structure and bootstrapping without domain-specific logic.

Contains: - Solution layout (Domain, Application, Infrastructure, API) - Program/Host bootstrapping - Common health checks and resilience - Base testing infrastructure - Base documentation

Value: Provides the foundation for all microservices. Changes here benefit all specialized templates automatically.

Layer 3: Specialized Templates

What: Domain-specific templates (Identity, Auth, Audit, Worker) that add domain logic on top of base.

Contains: - Domain-specific projects (Identity.Api, Identity.Domain, etc.) - Domain-specific tests - Domain-specific documentation - Overlay metadata for template composition

Value: Enables rapid creation of domain-specific services by adding only what's unique to that domain.

How It Works

Build Time (Developer Experience)

When developers work on templates:

  1. Clone specialized template repository (e.g., Identity Template)
  2. Base template included automatically via git submodule
  3. Open solution - works as normal .NET solution
  4. Build and test - everything just works
  5. Add domain logic - extend base, don't modify it

Result: Developers work on real, concrete applications, not abstract templates.

Generation Time (Factory Composition)

When the Factory generates a service:

  1. Load base template - code, docs, metadata
  2. Apply overlays - Identity, Worker, etc.
  3. Resolve tokens - ServiceName, Namespace, etc.
  4. Output final template - ready for dotnet new or Factory use

Result: Flexible template composition enables recipe-based generation (e.g., Identity + Worker).

Key Benefits

No Duplication

  • Common infrastructure written once in base template
  • Shared libraries delivered as NuGet packages
  • Specialized templates add only domain-specific code

Faster Development

  • Start from proven base template
  • Add domain logic, don't rebuild infrastructure
  • Reuse base testing patterns and documentation

Consistency

  • All services follow same architectural patterns
  • Same structure, same bootstrapping, same infrastructure
  • Predictable codebase structure

Maintainability

  • Base improvements propagate to all templates automatically
  • Changes to shared libraries benefit all services
  • Clear separation of concerns (base vs. domain)

Flexibility

  • Specialized templates add domain logic without modifying base
  • Overlays enable recipe-based composition
  • New domains can be added quickly

Value Proposition Diagram

flowchart LR
    subgraph Input["Input"]
        DEV[Developer Time]
        BASEINFRA[Base Infrastructure]
    end

    subgraph Process["Three-Layer Architecture"]
        LAYERS[Layers:<br/>Libraries → Base → Specialized]
    end

    subgraph Output["Output"]
        SPEED[Faster Development]
        QUALITY[Consistent Quality]
        MAINTAIN[Easier Maintenance]
        SCALE[Scalable Templates]
    end

    DEV --> LAYERS
    BASEINFRA --> LAYERS
    LAYERS --> SPEED
    LAYERS --> QUALITY
    LAYERS --> MAINTAIN
    LAYERS --> SCALE

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

Use Cases

Creating a New Specialized Template

Scenario: Need a new "Notification" template for sending emails and push notifications.

Process: 1. Create new repository with base template as submodule 2. Add Notification domain projects (Notification.Api, Notification.Domain, etc.) 3. Implement domain-specific logic 4. Add domain-specific tests using base test infrastructure 5. Define overlay metadata for template composition

Result: New template ready in days, not weeks. Reuses all base infrastructure.

Updating Base Infrastructure

Scenario: Need to add new observability feature to all microservices.

Process: 1. Update base template with new observability code 2. Update shared libraries if needed 3. Update submodule references in specialized templates 4. All templates automatically get new feature

Result: One change benefits all templates. No need to update each template individually.

Composing Templates

Scenario: Need Identity service with Worker functionality.

Process: 1. Factory uses recipe: base + Identity overlay + Worker overlay 2. Overlays are composed at generation time 3. Final template includes both Identity and Worker functionality

Result: Flexible composition enables many template variants from base + overlays.

For technical deep-dives, see:

Summary

ConnectSoft's three-layer template architecture eliminates duplication while maintaining flexibility. Shared libraries provide common infrastructure, base template provides the microservice kernel, and specialized templates add domain-specific functionality. This architecture enables faster development, consistent quality, and easier maintenance across all ConnectSoft-generated systems.

The separation between build time (normal .NET solutions) and generation time (template composition) provides excellent developer experience while enabling flexible template composition for the Factory.