Skip to content

ADR-00xz: Foundation Documentation Migration to Central Repository

  • Status: accepted
  • Deciders: ConnectSoft Architecture Team
  • Date: 2026-01-20

Context and Problem Statement

ConnectSoft maintains multiple templates (Microservice, API Gateway, Identity, Auth Server, etc.) that share common foundation documentation covering architecture patterns, technologies, and best practices. These foundation files were originally located in individual template repositories (e.g., ConnectSoft.MicroserviceTemplate/Docs/public/foundations/), leading to:

  • Documentation Duplication - Same foundation documentation duplicated across multiple template repositories
  • Maintenance Burden - Updates to foundation documentation require changes in multiple repositories
  • Inconsistency - Foundation documentation drifts apart across templates over time
  • Discoverability Issues - Developers must look in multiple repositories to find documentation
  • Version Control Complexity - Foundation documentation changes require PRs across multiple repositories
  • Template-Specific Confusion - Mixing general/abstract documentation with template-specific implementation details

We need a way to centralize general foundation documentation while keeping template-specific implementation details in their respective repositories.

Decision Drivers

  • Need to eliminate documentation duplication across templates
  • Requirement to maintain a single source of truth for foundation documentation
  • Need for foundation documentation updates to propagate automatically
  • Requirement to separate general/abstract documentation from template-specific details
  • Need to improve discoverability and navigation of documentation
  • Requirement to reduce top-level categories in documentation TOC for better organization
  • Need to support documentation reuse across all ConnectSoft templates

Considered Options

Option 1: Keep Documentation in Template Repositories

Approach: Continue maintaining foundation documentation in each template repository.

Pros:

  • Documentation co-located with code
  • Template-specific context preserved

Cons:

  • Massive documentation duplication
  • Changes require updates in multiple repositories
  • Documentation drifts apart over time
  • Poor discoverability
  • Difficult to maintain consistency
  • No centralized documentation site

Option 2: Central Documentation Repository (Chosen)

Approach: Migrate all general/abstract foundation documentation to ConnectSoft.Documentation repository, organize into logical categories, and maintain template-specific documentation in template repositories.

Pros:

  • Single source of truth for foundation documentation
  • No duplication - documentation maintained once
  • Centralized documentation site with improved navigation
  • Better discoverability - all foundation docs in one place
  • Reduced TOC complexity - consolidated categories
  • Template-specific docs remain in template repos where they belong
  • Foundation documentation can be referenced from all templates
  • Easier to maintain and update

Cons:

  • Documentation separated from template code
  • Requires link updates when referencing foundation docs
  • Initial migration effort required

Option 3: Documentation as NuGet Package

Approach: Package foundation documentation as a NuGet package or similar artifact.

Pros:

  • Versioned documentation
  • Can be referenced by templates

Cons:

  • Complex build and deployment process
  • Documentation not easily browsable
  • Doesn't solve discoverability issues
  • Over-engineered for documentation needs

Decision Outcome

Chosen option: Option 2: Central Documentation Repository, because it provides:

  • Single source of truth for all foundation documentation
  • Improved discoverability and navigation
  • Reduced maintenance burden
  • Better organization with consolidated TOC structure
  • Clear separation between general and template-specific documentation

Migration Strategy

  1. Identify General vs Template-Specific Documentation

    • General/Abstract: Architecture patterns, technologies, best practices applicable to all templates
    • Template-Specific: Implementation details, project structures, template-specific models

  2. Organize Documentation into Logical Categories

    • Architecture Patterns (DDD, Clean Architecture, CQRS, Event Sourcing, etc.)
    • Communication Patterns (REST API, gRPC, GraphQL, SignalR, etc.)
    • Technology Stack (Actor Model, Messaging, Persistence, etc.)
    • Observability (Logging, Metrics, Tracing, OpenTelemetry, etc.)
    • Security (Authentication, Authorization, Secrets Management, etc.)
    • Testing (Unit Testing, Integration Testing, BDD, etc.)
    • Infrastructure (Kubernetes, Docker, Infrastructure as Code, etc.)
    • Cross-Cutting Concerns (Validation, Exception Handling, Feature Flags, etc.)

  3. Generalize Template-Specific Content

    • Replace "Microservice Template" with "ConnectSoft Templates"
    • Generalize examples to work for all template types
    • Focus on patterns rather than implementation details

  4. Update TOC Structure

    • Reduce top-level categories from 13 to 8-9
    • Consolidate related sections (SaaS Solutions + SaaS, Development Stack + Deployment + AI/ML, etc.)
    • Organize cross-cutting concerns into subcategories

  5. Maintain Template-Specific Documentation

    • Keep template-specific files in template repositories
    • Update README.md in foundations to track migrated vs remaining files
    • Provide clear guidance on when to reference central docs vs template-specific docs

Consequences

Positive

  • Single Source of Truth: All foundation documentation in one repository
  • Reduced Duplication: Documentation maintained once, referenced by all templates
  • Better Organization: Consolidated TOC with logical subcategories
  • Improved Discoverability: Central documentation site with search capabilities
  • Easier Maintenance: Updates to foundation docs happen in one place
  • Clear Separation: General docs vs template-specific docs clearly distinguished
  • Scalability: Easy to add new templates without duplicating foundation docs

Negative

  • Link Updates Required: Internal links in migrated files need updating
  • Migration Effort: Initial migration and generalization work required
  • Separation from Code: Foundation docs no longer co-located with template code
  • Cross-Repository References: Templates must reference docs in different repository

Neutral

  • Documentation Structure: More organized but different from previous structure
  • TOC Changes: Navigation structure changed but improved

Implementation Details

Files Migrated

Architecture Patterns:

  • Event Sourcing, Repository Pattern, Saga Pattern, Outbox Pattern, Specification Pattern
  • Application Model, Domain Model, Flow Model
  • CQRS Pattern (merged into existing CQRS doc)
  • DDD Pattern (merged into existing DDD doc)
  • Clean Architecture Pattern (merged into existing Clean Architecture doc)

Communication Patterns:

  • REST API, gRPC, GraphQL, SignalR, HTTP Client, CoreWCF, Messaging Model
  • Service Model

Technology Stack:

  • Actor Model (Orleans, Dapr, Akka.NET, clustering configurations)
  • Messaging (MassTransit, NServiceBus)
  • Persistence (NHibernate, MongoDB, Persistence and Data Modeling)
  • Background Jobs (Hangfire)

Observability:

  • Logging, Metrics, Distributed Tracing, OpenTelemetry, Application Insights
  • AI Observability, Observability Stacks, Production Patterns, Scaling, Security
  • Latency Telemetry, HTTP Logging, Resource Monitoring

Security:

  • Authentication, Authorization, Secrets Management, Data Redaction, Security Overview

Testing:

  • Unit Testing, Integration Testing, BDD Testing, Architecture Tests
  • Mocking Strategies, Test Data Management

Infrastructure:

  • Kubernetes, Docker Compose, Containerization, Infrastructure as Code
  • Hosting Models, Hosting, Service Fabric
  • Infrastructure Model (Azure), Infrastructure Model (AWS)

Cross-Cutting Concerns:

  • API Management (Versioning, CORS, Swagger, Scalar, Rate Limiting, Request Timeout, Header Propagation, Response Compression)
  • System Reliability (Resiliency, Service Discovery, Health Checks)
  • Data Management (Database Migrations, Caching, Object Mapping)
  • Configuration & Feature Management (Configuration, Azure App Configuration, Feature Flags, Central Package Management)
  • Error Handling & Validation (Validation, Exception Handling)
  • Documentation (Diagram as Code, Documentation as Code)
  • AI & Machine Learning (AI Extensions, Model Context Protocol, Semantic Kernel, Vector Ingestion, Microsoft Bot Framework)
  • DevOps & Automation (CI/CD Pipelines, Azure Functions)
  • Code Quality & Standards (Naming Conventions)
  • Compliance & Standards (Audit.NET)
  • Localization

Files Remaining in Template Repositories

Template-Specific Files:

  • architecture-model.md - Template-specific architecture model
  • solution-structure.md - Template solution structure
  • startup-warmup.md - Template-specific startup and warmup patterns

TOC Reorganization

Before: 13 top-level categories After: 9 top-level categories

Consolidations:

  • SaaS Solutions + SaaS → SaaS
  • Development Stack + Deployment and Automation + AI and Machine Learning → Development
  • Guides and Use Cases → Guides
  • Azure DevOps → Operations

New Subcategories:

  • Architecture > Patterns (with Application Model, Domain Model, Flow Model)
  • Architecture > Communication (with Service Model)
  • Architecture > Infrastructure (with Hosting, Infrastructure Model Azure/AWS)
  • Cross-Cutting Concerns > API Management, System Reliability, Data Management, etc.

References

Notes

  • All migrated files were generalized from "Microservice Template" to "ConnectSoft Templates"
  • Template-specific implementation details were removed or generalized
  • Internal links in migrated files were updated to reflect new locations
  • README.md in template foundations directories was updated to track migrations
  • Documentation remains accessible from template repositories via links to central docs