Skip to content

title: Template Layering and Reuse description: Comprehensive guide to ConnectSoft's three-layer template architecture: shared libraries, base service template, and specialized templates with overlays and submodules. tags: - templates - architecture - layering - reuse - submodules - overlays

Template Layering and Reuse

This document provides a comprehensive 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.

Artifact output modes

Backend templates now distinguish --artifact-kind solution from --artifact-kind template. Use solution for clean generated application code and template when the generated output must become another authoring-ready template layer. See Template Artifact Model.

Goals

The template layering architecture is designed to achieve:

  • Zero Duplication - No code, docs, or configuration is duplicated across templates
  • Maximum Reuse - Common infrastructure is shared via libraries and base template
  • Build-Time Development - Templates remain fully buildable as normal .NET solutions
  • Generation-Time Composition - Final templates are composed from base + overlays at generation time
  • Domain Flexibility - Specialized templates add domain-specific logic without modifying base
  • Maintainability - Changes to base infrastructure propagate to all templates automatically

Practical playbook

For Layer 3 repos that use a base-template/ submodule (MSBuild, Docker, CI, template installer, overlays): follow Extended templates: full multi-layer alignment playbook. It uses IdentityTemplate + BaseTemplate as the canonical walkthrough.

DI Extensibility in Layering

Layer 2 (ConnectSoft.BaseTemplate) owns the default DI orchestration pipeline. Layer 3 templates should extend it via registration hooks, not by copying full DI pipelines.

Use the canonical guide: BaseTemplate DI Extensibility.

Compile-time feature flags and Central Package Management for extended repos are separate from DI; see MSBuild layering in extended template repos below.

Documentation Layering

The same three-layer model applies to documentation. Documentation is not copied downward as a parallel knowledge base. It is owned at the lowest layer that can describe the topic without product-specific assumptions.

Documentation layer Owner What it documents
Canonical ConnectSoft.Documentation Shared architecture, cross-cutting concerns, technology guidance, development standards, template governance, and generated-docs policy.
Layer 2 implementation ConnectSoft.BaseTemplate How the base service kernel implements canonical concepts: projects, DI hooks, options, feature flags, package wiring, tests, and troubleshooting.
Layer 3 overlay Specialized template repos What the template adds, replaces, disables, or configures differently from BaseTemplate.
Generated solution Consumer repo Curated local runbook, enabled-feature matrix, inherited implementation references, and canonical links.

This prevents overlap:

  • Do not duplicate canonical explanations of observability, resilience, security, persistence, messaging, AI, testing, or localization in template repos.
  • Do keep implementation details close to the owning code when those details are specific to BaseTemplate or a Layer 3 overlay.
  • Do use docs-manifest.yml to map enabled features to canonical docs, inherited BaseTemplate docs, and local overlay docs.
  • Do include only a curated documentation bundle in generated solutions; link to canonical docs by default.

The operational policy is defined in Template Documentation Policy and Documentation Source of Truth.

The Three-Layer Model

ConnectSoft templates are organized into three distinct layers, each with specific responsibilities:

flowchart TB
    subgraph Layer1["Layer 1: Shared Libraries"]
        LIB[ConnectSoft.Extensions NuGet packages]
    end

    subgraph Layer2["Layer 2: Base Service Template"]
        BASE[ConnectSoft.BaseTemplate<br/>Model projects and host<br/>Bootstrapping and infrastructure]
    end

    subgraph Layer3["Layer 3: Specialized Templates"]
        IDENTITY[ConnectSoft.IdentityTemplate and others]
        WORKER[Worker and domain templates]
    end

    Layer1 -->|NuGet CPM| Layer2
    Layer1 -->|NuGet CPM| Layer3
    Layer2 -->|Git submodule base-template| Layer3
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, OpenTelemetry wiring helpers)
  • Messaging (MassTransit and NServiceBus integration packages)
  • Persistence (NHibernate, MongoDB, database model helpers)
  • Options, validation, compliance, service discovery, health checks, and more

Characteristics:

  • Delivered as NuGet packages
  • Used by all templates and services
  • Versioned independently (pinned in ConnectSoft.BaseTemplate Directory.Packages.props)
  • No domain-specific logic

Catalog: The authoritative package list and MSBuild conditions are in ConnectSoft.Extensions catalog.

SaaS platform program (Layer 1 — additional):

  • ConnectSoft.Extensions.Saas.* — Tenant context abstractions, ASP.NET Core middleware, options, testing helpers (ConnectSoft.Extensions.Saas.* libraries). One repository per package. These packages are introduced in Phase 2 of the SaaS roadmap after ConnectSoft.Saas.*Template repositories prove layout and ServiceModel packaging; Phase 1 templates may use inlined stubs marked for replacement.

SaaS platform program (Layer 2 — submodule for SaaS templates):

  • ConnectSoft.BaseTemplate — The Git submodule used inside each ConnectSoft.Saas.<Context>Template repository (SaaS backend template + scaffold). This is the SaaS program’s base kernel for new bounded-context templates; it is not rebranded as “MicroserviceTemplate.Base” in SaaS naming. See SaaS platform — solution plan.

SaaS platform program (Layer 3):

  • ConnectSoft.Saas.<Context>Template — One specialized template repo per in-scope bounded context (Tenants, Product catalog, Entitlements, Billing, Metering), each submoduling ConnectSoft.BaseTemplate and shipping dotnet new output plus ServiceModel projects. See SaaS bounded contexts and ConnectSoft.Saas.*Template matrix.

Layer 2: Base Service Template (ConnectSoft.BaseTemplate)

Purpose: One canonical repository containing the microservice "kernel": shared model projects, host, bootstrapping, and infrastructure without product-domain logic.

Responsibilities:

  • Solution layout: prefixed projects under src/ such as ConnectSoft.BaseTemplate (host), ConnectSoft.BaseTemplate.DomainModel, ConnectSoft.BaseTemplate.ApplicationModel, ConnectSoft.BaseTemplate.Application, ConnectSoft.BaseTemplate.PersistenceModel.*, ConnectSoft.BaseTemplate.FlowModel.*, ConnectSoft.BaseTemplate.MessagingModel, ConnectSoft.BaseTemplate.ServiceModel.*, ConnectSoft.BaseTemplate.Options, ConnectSoft.BaseTemplate.Metrics, plus optional stacks (actors, schedulers, AI, MCP, etc.) as enabled in the solution
  • Program/Host bootstrapping and DI orchestration (see BaseTemplate DI Extensibility)
  • Common health checks, resilience patterns
  • Base CI/CD pipelines (Azure Pipelines; shared templates from ConnectSoft.AzurePipelines)
  • Base testing infrastructure
  • Base template metadata (/template/template.json)
  • Layer 2 implementation documentation and docs-manifest.yml
  • Central Package Management: Directory.Packages.props pins ConnectSoft.Extensions.* and third-party versions

Characteristics:

  • Single canonical repository (ConnectSoft.BaseTemplate)
  • No product-domain logic (no Identity product domain, etc.)
  • Fully buildable as a normal .NET solution
  • Used as git submodule base-template/ by specialized templates

Structure (illustrative — see repo ConnectSoft.BaseTemplate.slnx for the full set): 

ConnectSoft.BaseTemplate/
├── src/
│   ├── ConnectSoft.BaseTemplate/              # Host
│   ├── ConnectSoft.BaseTemplate.Application/
│   ├── ConnectSoft.BaseTemplate.ApplicationModel/
│   ├── ConnectSoft.BaseTemplate.DomainModel/
│   ├── ConnectSoft.BaseTemplate.DomainModel.Impl/
│   ├── ConnectSoft.BaseTemplate.EntityModel/
│   ├── ConnectSoft.BaseTemplate.PersistenceModel.NHibernate/
│   ├── ConnectSoft.BaseTemplate.ServiceModel.RestApi/
│   ├── ConnectSoft.BaseTemplate.ServiceModel.Grpc/
│   └── … (FlowModel, MessagingModel, optional stacks, etc.)
├── tests/
├── Directory.Build.props
├── Directory.Packages.props
├── azure-pipelines.yml
└── template/
    └── template.json

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
  • Overlay-specific documentation and docs-manifest.yml
  • 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

Structure example (ConnectSoft.IdentityTemplate — see ConnectSoft.IdentityTemplate.slnx): 

ConnectSoft.IdentityTemplate/
├── base-template/                         # Git submodule -> ConnectSoft.BaseTemplate
├── build/
│   └── DisableMicrosoftExtensionsStackForMinimalHost.props
├── ConnectSoft.TemplateRepositoryDirectory.Build.props
├── Directory.Build.props                  # Imports template repo props + base-template/Directory.Build.props
├── Directory.Packages.props                 # Imports base-template/Directory.Packages.props
├── ConnectSoft.IdentityTemplate.slnx        # Base projects under /BaseTemplate/; Identity *Model projects at repo root
├── ConnectSoft.IdentityTemplate/            # Host
├── ConnectSoft.IdentityTemplate.Application/   # Replaces ConnectSoft.BaseTemplate.Application in this solution
├── ConnectSoft.IdentityTemplate.DomainModel/
├── ConnectSoft.IdentityTemplate.ApplicationModel/
├── ConnectSoft.IdentityTemplate.PersistenceModel.NHibernate/
├── ConnectSoft.IdentityTemplate.ServiceModel.RestApi/
├── … (other Identity *Model projects)
├── ConnectSoft.IdentityTemplate.UnitTests/
├── ConnectSoft.IdentityTemplate.AcceptanceTests/
├── Docs/
└── azure-pipelines.yml

Base Service Template and Specialized Templates

Base Template Responsibilities

The base template provides:

  1. Solution Structure - Clean Architecture expressed as ConnectSoft.BaseTemplate.* model projects (DomainModel, ApplicationModel, PersistenceModel, ServiceModel, FlowModel, MessagingModel, host, tests), not as four generic single-folder names
  2. Bootstrapping - Program.cs, Host setup, DI configuration
  3. Common Infrastructure - Health checks, resilience, observability wiring
  4. Base Testing - Test infrastructure, base test classes, test helpers
  5. Base Documentation - Architecture docs, testing guides, common patterns
  6. Template Metadata - Base template.json with common parameters

Specialized Template Responsibilities

Specialized templates add:

  1. Domain Logic - Domain-specific entities, aggregates, domain services
  2. Domain Infrastructure - Domain-specific repositories, external service clients
  3. Domain APIs - Domain-specific controllers, endpoints, request/response models
  4. Domain Tests - Domain-specific unit and acceptance tests
  5. Domain Documentation - Domain-specific flows, endpoints, metrics
  6. Overlay Metadata - Extend files that add to base template.json

Relationship: Submodules at Build Time

At build time, specialized templates include the base template as a git submodule:

flowchart LR
    subgraph IdentityRepo["ConnectSoft.IdentityTemplate"]
        BASE[base-template submodule]
        IDENTITY[ConnectSoft.IdentityTemplate.* projects]
        TESTS[ConnectSoft.IdentityTemplate.*Tests]
        DOCS[Docs/]
    end

    subgraph BaseRepo["ConnectSoft.BaseTemplate"]
        BASESRC[src ConnectSoft.BaseTemplate.*]
        BASETESTS[tests]
    end

    BASE -.->|points to| BaseRepo
Hold "Alt" / "Option" to enable pan & zoom

Benefits:

  • Base template changes propagate to all specialized templates
  • No code duplication
  • Each template repo is self-contained and buildable
  • Clear separation of concerns

MSBuild layering in extended template repos

Extended templates (for example ConnectSoft.IdentityTemplate) must compile against the same Directory.Build.props feature flags as ConnectSoft.BaseTemplate while only including a subset of base projects in the solution. Identity therefore wires MSBuild in this order:

  1. Repo root Directory.Build.props imports ConnectSoft.TemplateRepositoryDirectory.Build.props, which sets ConnectSoftBaseTemplateDirectoryPostImport to build/DisableMicrosoftExtensionsStackForMinimalHost.props.
  2. The same root file imports base-template/Directory.Build.props (from the submodule).
  3. Base template props apply analyzers and optional stacks; the post-import minimal-host file turns off flags for stacks Identity does not build (for example AI/agent/vector, MongoDB, HangFire, Log4Net, and optional service models), so MSBuild does not expect outputs for projects outside the solution.
  4. Projects that live only under base-template/src/... still load base-template/Directory.Build.props, which can apply DisableMicrosoftExtensionsStackForMinimalHost.props via a fallback path when ConnectSoftBaseTemplateDirectoryPostImport is unset—see comments in the base template props file.

Satellite vs host (CPM): the entry DisableMicrosoftExtensionsStackForMinimalHost.props file uses two conditional top-level Import elements: ExtendedHost.BaseTemplateSatelliteDefaults.props for paths under base-template, and a strict minimal *Host.props fragment for Layer 3 projects. That keeps satellite Use* evaluation aligned with Layer 2 Directory.Packages.props and avoids MSB4067 (Import inside Choose). NU1010 from unconditional satellite PackageReference items is fixed in ConnectSoft.BaseTemplate (Option A: Condition on refs). Do not duplicate PackageVersion rows in Layer 3 to paper over that—except rare third-party cases; see Extended templates: full multi-layer alignment playbook — MSBuild and Central Package Management.

Central Package Management: the extended repo’s Directory.Packages.props should import base-template/Directory.Packages.props and add only template-specific PackageVersion rows (with optional overrides using Remove—see Identity’s file comments). Avoid a parallel build/CentralPackageVersions.MinimalHost.props shim for BaseTemplate optional stacks once the submodule carries Option A.

flowchart TD
  hostProps[RepoRoot Directory.Build.props]
  tmplProps[ConnectSoft.TemplateRepositoryDirectory.Build.props]
  baseProps[base-template Directory.Build.props]
  minimal[build DisableMicrosoftExtensionsStackForMinimalHost.props]
  hostProps --> tmplProps
  hostProps --> baseProps
  tmplProps --> minimal
  baseProps --> minimal
Hold "Alt" / "Option" to enable pan & zoom

CI/CD: both ConnectSoft.BaseTemplate and ConnectSoft.IdentityTemplate reference shared pipeline templates from ConnectSoft/ConnectSoft.AzurePipelines. The base repo’s azure-pipelines.yml is heavily parameterized (including conditional service containers). Identity’s pipeline is a concrete variant (fixed containers and variables such as SQL credentials) suited to its tests; treat it as a sibling pattern, not an unmodified copy.

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 (repository layout): 

ConnectSoft.IdentityTemplate/
├── base-template/                    # Submodule: ConnectSoft.BaseTemplate
│   └── src/ConnectSoft.BaseTemplate.*/
├── ConnectSoft.IdentityTemplate.slnx
├── ConnectSoft.IdentityTemplate.*/
└── ConnectSoft.IdentityTemplate.*Tests/

Workflow:

  1. Developer clones ConnectSoft.IdentityTemplate
  2. Initialize the base-template submodule (git submodule update --init --recursive)
  3. Open ConnectSoft.IdentityTemplate.slnx
  4. Build and test work immediately
  5. All base infrastructure is available

Generation Time (dotnet new / template packaging)

Goal: Produce either a clean, materialized consumer solution (--artifact-kind solution) or an authoring-ready next-layer template artifact (--artifact-kind template).

Characteristics:

  • Each Layer 3 repo's CI pipeline packs the repo, then runs base-template/build/Invoke-TemplateCompose.ps1 to compose a final .template.config/template.json from ConnectSoft.BaseTemplate's canonical metadata plus the repo's own (small) extend file — there is no separate "recipe" file and no generic overlay-merge engine; the compose profile (Simple / Identity / ApiGateway / Microservice) selects one fixed transform per repo family.
  • dotnet new <shortname> --artifact-kind solution|template resolves tokens (ServiceName, RootNamespace, etc.) via the standard .NET templating engine's own symbol substitution — no separate token-resolution pass.
  • Output is pushed as a NuGet package to Azure Artifacts by each repo's own pipeline; there is no separate Factory push-to-Azure-DevOps step.

For the exact merge rules per compose profile, the extend-file field reference, and the _template.config authoring-ready mechanism, see Template Metadata Composition — that document is the source of truth for how composition actually works; this section only summarizes it in the context of the three-layer model.

Submodules at Build Time vs Composition 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: Compose profiles, not overlays

What: Invoke-TemplateCompose.ps1 composes the final .template.config/template.json from base + the repo's own extend file, then dotnet new generates from the composed template. There is no multi-overlay stacking, no // @@MODULE_REGISTRATION_BEGIN/END marker-based file patching, and no YAML "recipe" describing a layer stack — each Layer 3 repo has exactly one extend file and one compose profile.

Why this shape (not generic overlays):

  • One repo, one extend file, one compose profile keeps the merge rules small and auditable — see Template Metadata Composition for the complete, real field reference per profile.
  • Feature composition (e.g. a repo needing both Identity-style domain logic and Worker-style scheduling) is expressed as symbol defaults in that repo's own extend file (identityOverrides.defaults), not as a second overlay applied on top of a first.

Result: Each Layer 3 repo produces one composed template per pointer/pack, deterministically, from its own extend file — no cross-repo recipe state to keep in sync.

Multiple first-class Layer 3 repos, not "Identity + Worker overlay stacking"

ConnectSoft.WorkerTemplate and ConnectSoft.ApiGatewayTemplate are first-class Layer 3 repositories in their own right (not overlays applied on top of Identity): each uses its own base-template/ submodule, its own MSBuild/CPM import chain, and its own extend file — see Extended templates: full multi-layer alignment playbook.

Build-time layout follows the same ConnectSoft.* model-project pattern as ConnectSoft.IdentityTemplate (host + DomainModel, ApplicationModel, ServiceModel, optional worker/scheduler projects); see the live solution and submodule for exact project names.

Docs Reuse (Base + Specialized)

Documentation follows the same layering pattern as code.

Build-Time Docs (Template Repos)

Base repo: 

ConnectSoft.BaseTemplate/
└── docs/   # if present; many repos use Docs/ or embedded template docs

Identity repo (example): 

ConnectSoft.IdentityTemplate/
├── base-template/              # Submodule includes base docs when published there
└── Docs/                     # Identity-specific MkDocs sources (see repo mkdocs.yml)

mkdocs.yml (pattern): include both submodule paths and repo-local Docs/ entries as needed for your site.

Result: At build time, docs reference both base (via submodule) and specialized docs. No physical merge needed.

Generation-Time Docs (Final Service)

Generated output does not physically copy-and-merge docs from base and overlay directories into namespaced subfolders. Each repo's docs-manifest.yml maps its enabled features to the curated set of docs that should ship in generated output (canonical links for cross-cutting topics, inherited BaseTemplate docs for implementation detail, local overlay docs for what the repo adds or changes) — see Template Documentation Policy for the exact policy docs-manifest.yml implements. Which of those docs are actually present in a given generated artifact follows the same artifact-kind rules as code: --artifact-kind solution excludes template-authoring docs (see Template Artifact Model); --artifact-kind template preserves them.

Result: Generated output has the curated documentation bundle its docs-manifest.yml selects, not every base + overlay doc physically duplicated.

Template Metadata Composition – Overview

Template metadata (.template.config/template.json) follows the same composition pattern. See Template Metadata Composition for the complete field reference and merge rules.

Key Points:

  • ConnectSoft.BaseTemplate defines the canonical .template.config/template.json with the full symbol set and sources[]
  • Each Layer 3 repo defines one extend file (e.g., identity.template.extend.json) under template/
  • Invoke-TemplateCompose.ps1 composes base + the repo's extend file at pack time, per compose profile (Simple/Identity/ApiGateway/Microservice)
  • The composed .template.config/template.json includes base's full symbol set plus the repo's identity/description/defaults overrides

Practical example: ConnectSoft.IdentityTemplate

Repository structure

See ConnectSoft.IdentityTemplate. At a high level:

  • base-template/ — git submodule pointing at ConnectSoft.BaseTemplate
  • ConnectSoft.IdentityTemplate.slnx — includes a subset of base-template/src/ConnectSoft.BaseTemplate.* projects (solution folder /BaseTemplate/) plus all ConnectSoft.IdentityTemplate.* projects at the repository root
  • ConnectSoft.IdentityTemplate.Application is used instead of ConnectSoft.BaseTemplate.Application in this solution (same pattern as other extended templates that fork the application project)
  • MSBuild — root Directory.Build.props, ConnectSoft.TemplateRepositoryDirectory.Build.props, and build/DisableMicrosoftExtensionsStackForMinimalHost.props (see MSBuild layering)
  • NuGet — Directory.Packages.props imports the base template’s CPM file

Solution file structure

From base (submodule), examples:

  • base-template/src/ConnectSoft.BaseTemplate/ConnectSoft.BaseTemplate.csproj (host reference model; Identity host is ConnectSoft.IdentityTemplate)
  • base-template/src/ConnectSoft.BaseTemplate.ApplicationModel/...
  • base-template/src/ConnectSoft.BaseTemplate.DomainModel/...
  • Additional base projects as included in ConnectSoft.IdentityTemplate.slnx

From Identity template (repo root), examples:

  • ConnectSoft.IdentityTemplate/ConnectSoft.IdentityTemplate.csproj (host)
  • ConnectSoft.IdentityTemplate.Application/ConnectSoft.IdentityTemplate.Application.csproj
  • ConnectSoft.IdentityTemplate.DomainModel/ConnectSoft.IdentityTemplate.DomainModel.csproj
  • ConnectSoft.IdentityTemplate.ServiceModel.RestApi/...
  • ConnectSoft.IdentityTemplate.UnitTests/..., ConnectSoft.IdentityTemplate.AcceptanceTests/...

Build process

  1. Clone repository: 

    git clone <ConnectSoft.IdentityTemplate-url>
cd ConnectSoft.IdentityTemplate
git submodule update --init --recursive

  2. Open solution: 

    dotnet sln ConnectSoft.IdentityTemplate.slnx

  3. Build: 

    dotnet build

  4. Test: 

    dotnet test

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

Generation Process

When CI packs and generates from ConnectSoft.IdentityTemplate (the same sequence applies to every Layer 3 repo, with that repo's own compose profile — see Template Metadata Composition):

  1. Stage the repo — Prepare-ExtendedTemplatePack.ps1 copies the repo and rewrites the staged base-template/Directory.Build.props.
  2. Compose metadata — Invoke-TemplateCompose.ps1 -ComposeProfile Identity merges identity.template.extend.json onto ConnectSoft.BaseTemplate's canonical .template.config/template.json.
  3. Pack and install — the composed content is packed as a NuGet installer package and installed into the dotnet new template hive.
  4. Generate — dotnet new connectsoft-identity --artifact-kind solution|template resolves symbols (ServiceName, RootNamespace, ArtifactKind, etc.) via the standard .NET templating engine and writes the output.
  5. Build and validate — CI builds the generated output and runs Validate-TemplateArtifactModel.ps1 against it for the artifact kind generated (see Template Artifact Model).

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
✅ Keep each repo's extend file to one compose profile - identityOverrides/apigatewayOverrides plus defaults, not a generic overlay-merge DSL
✅ Reference base docs via submodule at build time
✅ Curate generated docs via docs-manifest.yml 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