Template Integration - Audit Trail Platform (ATP)¶

Built from proven templates — ATP services leverage the ConnectSoft template ecosystem (Microservice, Gateway, Library, Blazor, Platform) with standardized patterns for Clean Architecture, DDD, event-driven design, CI/CD, and observability, enabling rapid, consistent, and maintainable service development at scale.

📋 Documentation Generation Plan¶

This document will be generated in 16 cycles. Current progress:

Cycle	Topics	Estimated Lines	Status
Cycle 1	Template Ecosystem Overview (1-2)	~3,000	⏳ Not Started
Cycle 2	Microservice Template Deep Dive (3-4)	~4,000	⏳ Not Started
Cycle 3	ATP Service Architecture from Templates (5-6)	~3,500	⏳ Not Started
Cycle 4	Template Instantiation & Customization (7-8)	~4,000	⏳ Not Started
Cycle 5	Template Options & Parameters (9-10)	~3,500	⏳ Not Started
Cycle 6	Shared Libraries & Extensions (11-12)	~3,000	⏳ Not Started
Cycle 7	API Gateway Template Integration (13-14)	~3,000	⏳ Not Started
Cycle 8	Library Template Usage (15-16)	~2,500	⏳ Not Started
Cycle 9	Blazor & Frontend Templates (17-18)	~3,000	⏳ Not Started
Cycle 10	Platform & Identity Templates (19-20)	~2,500	⏳ Not Started
Cycle 11	Template Packaging & Distribution (21-22)	~3,000	⏳ Not Started
Cycle 12	Template Versioning & Updates (23-24)	~3,000	⏳ Not Started
Cycle 13	CI/CD Pipeline Integration (25-26)	~3,500	⏳ Not Started
Cycle 14	Template Testing & Validation (27-28)	~2,500	⏳ Not Started
Cycle 15	Template Governance & Best Practices (29-30)	~3,000	⏳ Not Started
Cycle 16	AI-Powered Template Generation (31-32)	~3,000	⏳ Not Started

Total Estimated Lines: ~51,000

Purpose & Scope¶

This document provides the complete integration guide for how ATP leverages the ConnectSoft template ecosystem to build and maintain its microservices, libraries, frontends, and infrastructure with consistency, quality, and velocity.

Why Template-Based Development for ATP?

Consistency: All ATP services follow same architecture, patterns, and conventions
Quality: Templates embed proven patterns (DDD, Clean Architecture, event-driven)
Velocity: New services created in minutes, not weeks
Maintainability: Standardized structure simplifies onboarding and maintenance
Evolution: Template updates propagate improvements across all services
Compliance: Security, observability, and governance baked into templates
AI-Ready: Templates designed for autonomous agent instantiation

ConnectSoft Template Catalog

Template	Purpose	ATP Usage
Microservice Template	Backend services with DDD, Clean Architecture	All ATP services (Ingestion, Query, Policy, etc.)
API Gateway Template	Unified API gateway with routing, auth, rate limiting	ATP Gateway (entry point for all APIs)
Library Template	Shared libraries (domain, infrastructure)	ATP.Core, ATP.Extensions
API Library Template	Service agent clients	ATP client SDKs
Blazor Component Library	Reusable UI components	ATP admin UI components
Blazor Microfrontend	Independently deployable UI modules	ATP analytics, compliance dashboards
Blazor Shell Application	Host app for microfrontends	ATP admin portal shell
Auth Server Template	OAuth2/OIDC identity server	ATP Identity Service
Platform Template	Complete multi-tenant SaaS platform	ATP platform infrastructure
Umbraco CMS Template	Content management	ATP documentation/help center
Semantic Kernel Template	AI/ML skills library	ATP AI-powered analytics

Detailed Cycle Plan¶

CYCLE 1: Template Ecosystem Overview (~3,000 lines)¶

Topic 1: ConnectSoft Template Philosophy¶

What will be covered: - Template-Driven Development

Traditional Development:
- Start from scratch
- Copy/paste boilerplate
- Inconsistent patterns
- Manual configuration
- Hard to upgrade

Template-Driven Development (ConnectSoft):
- Start from proven templates
- Standardized architecture
- Consistent patterns
- Pre-configured infrastructure
- Automated upgrades

Template Principles

1. Clean Architecture by Default
   - Separation of concerns (API → Application → Domain → Infrastructure)
   - Dependency inversion
   - Testable components

2. Domain-Driven Design (DDD)
   - Aggregates, Entities, Value Objects
   - Domain Events
   - Repository pattern
   - Specification pattern

3. Cloud-Native Ready
   - Docker/Kubernetes manifests
   - Health checks, readiness probes
   - Observability (OpenTelemetry)
   - Configuration externalization

4. Event-Driven Architecture
   - MassTransit/NServiceBus integration
   - Outbox/Inbox patterns
   - Saga orchestration
   - CloudEvents compliance

5. Security First
   - JWT authentication
   - RBAC/ABAC authorization
   - Secrets management (Azure Key Vault)
   - Security headers, CORS

6. Compliance Ready
   - Audit logging
   - PII classification
   - GDPR/HIPAA/SOC2 controls
   - Retention policies

7. CI/CD Native
   - Azure Pipeline templates
   - Multi-stage deployments
   - Quality gates (tests, coverage, security scans)
   - GitOps manifests

Template Benefits for ATP

Speed:
- New service from template: 5 minutes
- New service from scratch: 2-4 weeks

Quality:
- Templates: 95%+ test coverage
- From scratch: 40-60% average

Consistency:
- All ATP services: Same structure, patterns, conventions
- Easy to navigate, understand, maintain

Maintenance:
- Template bug fix: Update once, propagate to all services
- From scratch: Fix in N services individually

Onboarding:
- New dev familiar with one service = familiar with all
- Documentation once, applies everywhere

Code Examples: - Template vs. scratch comparison - ATP service structure (from template) - Consistent patterns across services

Diagrams: - Template-driven development workflow - Template ecosystem architecture - ATP services mapped to templates

Deliverables: - Template philosophy overview - Benefits quantification - ATP template usage matrix

Topic 2: ConnectSoft Template Catalog¶

What will be covered: - Complete Template Inventory

// Template Catalog (Azure Artifacts feed)
public static class ConnectSoftTemplates
{
    // Backend Templates
    public const string Microservice = "ConnectSoft.MicroserviceTemplate.Installer";
    public const string ApiGateway = "ConnectSoft.ApiGatewayTemplate.Installer";

    // Library Templates
    public const string Library = "ConnectSoft.LibraryTemplate.Installer";
    public const string ApiLibrary = "ConnectSoft.ApiLibraryTemplate.Installer";
    public const string SemanticKernelLibrary = "ConnectSoft.SemanticKernelTemplate.Installer";

    // Frontend Templates
    public const string BlazorComponentLibrary = "ConnectSoft.Blazor.ComponentLibraryTemplate.Installer";
    public const string BlazorMicrofrontend = "ConnectSoft.Blazor.MicrofrontendTemplate.Installer";
    public const string BlazorShellApp = "ConnectSoft.Blazor.ShellTemplate.Installer";

    // Platform Templates
    public const string AuthServer = "ConnectSoft.AuthorizationServerTemplate.Installer";
    public const string Platform = "ConnectSoft.PlatformTemplate.Installer";
    public const string UmbracoCms = "ConnectSoft.UmbracoTemplate.Installer";

    // Documentation Templates
    public const string Documentation = "ConnectSoft.DocumentationTemplate.Installer";
    public const string AiSkills = "ConnectSoft.AISkillsLibraryTemplate.Installer";
}

Template Capabilities Matrix | Template | DDD | Clean Arch | Event-Driven | Actor Model | API (REST/gRPC) | UI (Blazor) | Docker | K8s | CI/CD | |----------|-----|------------|--------------|-------------|-----------------|-------------|--------|-----|-------| | Microservice | ✅ | ✅ | ✅ | ✅ (Orleans/Dapr) | ✅ | ❌ | ✅ | ✅ | ✅ | | API Gateway | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | | Library | Partial | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | | API Library | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ✅ | | Blazor Component | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | | Blazor Microfrontend | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | | Blazor Shell | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | | Auth Server | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | | Platform | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

Template Discovery & Installation

# List available ConnectSoft templates
dotnet new list connectsoft-

# Install Microservice Template from NuGet
dotnet new install ConnectSoft.MicroserviceTemplate.Installer::2.5.0

# Install from Azure Artifacts (private feed)
dotnet nuget add source https://pkgs.dev.azure.com/connectsoft/_packaging/PlatformTemplates/nuget/v3/index.json \
    --name ConnectSoftTemplates \
    --username az \
    --password $PAT

dotnet new install ConnectSoft.MicroserviceTemplate.Installer::2.5.0 \
    --add-source ConnectSoftTemplates

# List installed templates
dotnet new list

# Show template options
dotnet new connectsoft-microservice --help

Code Examples: - Template catalog reference - Installation scripts - Template discovery

Diagrams: - Template ecosystem map - Template capabilities matrix - Template selection decision tree

Deliverables: - Complete template catalog - Installation guide - Template selection guide

CYCLE 2: Microservice Template Deep Dive (~4,000 lines)¶

Topic 3: Microservice Template Architecture¶

What will be covered: - Template Structure

ConnectSoft.MicroserviceTemplate/
├── .template.config/
│   └── template.json                        # Template metadata and options
├── ConnectSoft.MicroserviceTemplate.sln     # Solution file
│
├── Application Layer/
│   ├── ConnectSoft.MicroserviceTemplate.Application/
│   │   ├── Program.cs                       # Entry point
│   │   ├── Startup.cs                       # DI container configuration
│   │   ├── appsettings.json                 # Configuration
│   │   ├── Dockerfile                       # Container build
│   │   └── Kubernetes/                      # K8s manifests
│   │
│   └── ConnectSoft.MicroserviceTemplate.ApplicationModel/
│       ├── NHibernateExtensions.cs         # Persistence setup
│       ├── MassTransitExtensions.cs        # Messaging setup
│       ├── OrleansExtensions.cs            # Actor model setup
│       ├── OpenTelemetryExtensions.cs      # Observability setup
│       └── HealthChecks/                    # Health check implementations
│
├── Domain Layer/
│   ├── ConnectSoft.MicroserviceTemplate.EntityModel/
│   │   ├── IMicroserviceAggregateRoot.cs   # Aggregate interface
│   │   └── PocoEntities/
│   │       └── MicroserviceAggregateRootEntity.cs  # POCO entity
│   │
│   ├── ConnectSoft.MicroserviceTemplate.DomainModel/
│   │   └── Impl/
│   │       └── MicroserviceAggregateRoot.cs  # Rich domain model
│   │
│   └── ConnectSoft.MicroserviceTemplate.MessagingModel/
│       └── MicroserviceAggregateRootCreatedEvent.cs  # Domain events
│
├── Infrastructure Layer/
│   ├── ConnectSoft.MicroserviceTemplate.PersistenceModel/
│   │   ├── Repositories/
│   │   │   └── IMicroserviceAggregateRootsRepository.cs
│   │   └── Specifications/
│   │       └── IMicroserviceAggregateRootsSpecification.cs
│   │
│   ├── ConnectSoft.MicroserviceTemplate.PersistenceModel.NHibernate/
│   │   ├── Mappings/
│   │   │   └── MicroserviceAggregateRootEntityMap.cs  # FluentNHibernate mappings
│   │   ├── Repositories/
│   │   │   └── MicroserviceAggregateRootsRepository.cs
│   │   └── Specifications/
│   │       └── MicroserviceAggregateRootsQueryableSpecification.cs
│   │
│   ├── ConnectSoft.MicroserviceTemplate.PersistenceModel.MongoDb/
│   │   # Alternative MongoDB persistence
│   │
│   ├── ConnectSoft.MicroserviceTemplate.DatabaseModel.Migrations/
│   │   └── MicroserviceMigration.cs        # FluentMigrator SQL migrations
│   │
│   └── ConnectSoft.MicroserviceTemplate.InfrastructureModel/
│       └── AzureInfrastructureStack.cs     # Pulumi IaC
│
├── API Layer/
│   ├── ConnectSoft.MicroserviceTemplate.ServiceModel.RestApi/
│   │   └── MicroserviceAggregateRootsServiceController.cs  # REST endpoints
│   │
│   ├── ConnectSoft.MicroserviceTemplate.ServiceModel.Grpc/
│   │   └── GrpcMicroserviceAggregateRootService.cs  # gRPC services
│   │
│   └── ConnectSoft.MicroserviceTemplate.ServiceModel.GraphQL/
│       # Optional GraphQL API
│
├── Actor Model Layer/ (Optional)
│   ├── ConnectSoft.MicroserviceTemplate.ActorModel.Orleans/
│   │   └── MicroserviceGrains/
│   │       └── MicroserviceAggregateRootGrain.cs   # Orleans grain
│   │
│   └── ConnectSoft.MicroserviceTemplate.FlowModel.MassTransit/
│       ├── MicroserviceAggregateRootLifeCycleSaga.cs  # Saga state machine
│       └── MicroserviceAggregateRootLifeCycleSagaState.cs
│
├── Testing Layer/
│   ├── ConnectSoft.MicroserviceTemplate.UnitTests/
│   │   # MSTest unit tests
│   │
│   ├── ConnectSoft.MicroserviceTemplate.AcceptanceTests/
│   │   # Reqnroll (SpecFlow) BDD tests
│   │
│   ├── ConnectSoft.MicroserviceTemplate.IntegrationTests/
│   │   # WebApplicationFactory integration tests
│   │
│   └── ConnectSoft.MicroserviceTemplate.ArchitectureTests/
│       # NetArchTest architecture validation
│
├── Configuration & Options/
│   ├── ConnectSoft.MicroserviceTemplate.Options/
│   │   ├── MicroserviceOptions.cs          # Strongly-typed config
│   │   ├── NHibernateOptions.cs
│   │   ├── MassTransitOptions.cs
│   │   └── OrleansOptions.cs
│   │
│   └── ConnectSoft.MicroserviceTemplate.HealthChecks/
│       # Custom health checks
│
├── Deployment/
│   ├── docker-compose/
│   │   └── docker-compose.yml              # Local dev environment
│   │
│   ├── kubernetes/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── ingress.yaml
│   │
│   └── helm/
│       └── microservice/
│           ├── Chart.yaml
│           ├── values.yaml
│           └── templates/
│
├── CI/CD/
│   ├── azure-pipelines.yml                 # Main pipeline
│   └── azure-pipelines-template.yml        # Reusable template
│
└── Docs/
    ├── README.md
    ├── ARCHITECTURE.md
    └── API.md

Layer Responsibilities

API Layer (Adapters):
- HTTP/gRPC/GraphQL endpoints
- Request validation
- DTO mapping
- Response formatting
- No business logic

Application Layer (Use Cases):
- Orchestration
- Transaction boundaries
- Policy enforcement
- Idempotency
- Cross-cutting concerns (logging, caching)

Domain Layer (Core):
- Aggregates, Entities, Value Objects
- Business rules and invariants
- Domain events
- Domain services
- Framework-independent

Infrastructure Layer (Adapters):
- Persistence (NHibernate, MongoDB)
- Messaging (MassTransit, NServiceBus)
- External services
- KMS, caching, observability

Template Configuration (.template.config/template.json)
```
                                                                                  
```
href="#__codelineno-7-1">{ "$schema": "http://json.schemastore.org/template", "author": "ConnectSoft", "classifications": [ "ConnectSoft", "Microservice Architecture", "Cloud Native", "Domain Driven Design", "Clean Architecture", "Event Driven Design" ], "identity": "ConnectSoft.MicroserviceTemplate", "name": "ConnectSoft Microservice Template", "shortName": "connectsoft-microservice", "sourceName": "ConnectSoft.MicroserviceTemplate", "preferNameDirectory": true, "tags": { "language": "C#", "type": "solution" }, "symbols": { "AggregateRootName": { "type": "parameter", "datatype": "string", "defaultValue": "MicroserviceAggregateRoot", "description": "Name of the main Aggregate Root Entity" }, "UseOrleans": { "type": "parameter", "datatype": "bool", "defaultValue": "false", "description": "Include Microsoft Orleans actor model" }, "UseMassTransit": { "type": "parameter", "datatype": "bool", "defaultValue": "true", "description": "Include MassTransit messaging" }, "UseNServiceBus": { "type": "parameter", "datatype": "bool", "defaultValue": "false", "description": "Include NServiceBus messaging" }, "UseMongoDb": { "type": "parameter", "datatype": "bool", "defaultValue": "false", "description": "Include MongoDB persistence" }, "UseNHibernate": { "type": "parameter", "datatype": "bool", "defaultValue": "true", "description": "Include NHibernate persistence" }, "UseGrpc": { "type": "parameter", "datatype": "bool", "defaultValue": "true", "description": "Include gRPC service" }, "UseGraphQL": { "type": "parameter", "datatype": "bool", "defaultValue": "false", "description": "Include GraphQL API" }, "UseOpenAI": { "type": "parameter", "datatype": "bool", "defaultValue": "false", "description": "Include OpenAI integration" }, "Docker": { "type": "parameter", "datatype": "bool", "defaultValue": "true", "description": "Include Docker support" } } }

Code Examples: - Complete template structure walkthrough - Layer-by-layer breakdown - Template configuration examples

Diagrams: - Template architecture diagram - Layer dependencies - Project relationships

Deliverables: - Microservice template reference - Layer responsibilities - Configuration guide

Topic 4: Template Capabilities & Features¶

What will be covered: - Built-In Features Matrix | Feature | Included | Configurable | Optional | |---------|----------|--------------|----------| | Clean Architecture | ✅ | ❌ | ❌ | | DDD (Aggregates, Entities, VOs) | ✅ | ✅ (naming) | ❌ | | Repository Pattern | ✅ | ❌ | ❌ | | Unit of Work | ✅ | ❌ | ❌ | | Specification Pattern | ✅ | ❌ | ❌ | | NHibernate ORM | ❌ | ❌ | ✅ | | MongoDB | ❌ | ❌ | ✅ | | FluentMigrator | ✅ (with NHibernate) | ❌ | ❌ | | MassTransit | ❌ | ❌ | ✅ | | NServiceBus | ❌ | ❌ | ✅ | | Outbox/Inbox Pattern | ✅ (with messaging) | ❌ | ❌ | | Saga State Machines | ✅ (with MassTransit) | ❌ | ❌ | | Microsoft Orleans | ❌ | ❌ | ✅ | | Dapr Actors | ❌ | ❌ | ✅ | | REST API (ASP.NET Core) | ✅ | ❌ | ❌ | | gRPC | ❌ | ❌ | ✅ | | GraphQL | ❌ | ❌ | ✅ | | SignalR | ❌ | ❌ | ✅ | | Swagger/OpenAPI | ✅ | ❌ | ❌ | | HealthChecks | ✅ | ✅ | ❌ | | OpenTelemetry | ✅ | ✅ | ❌ | | Serilog | ✅ | ✅ | ❌ | | Configuration (Options Pattern) | ✅ | ❌ | ❌ | | Azure Key Vault | ✅ | ✅ | ❌ | | Azure App Configuration | ✅ | ✅ | ❌ | | Docker | ❌ | ❌ | ✅ | | Kubernetes Manifests | ✅ (with Docker) | ✅ | ❌ | | Helm Charts | ✅ (with Docker) | ✅ | ❌ | | Pulumi IaC | ✅ | ✅ | ❌ | | Azure Pipelines | ✅ | ✅ | ❌ | | Unit Tests (MSTest) | ✅ | ❌ | ❌ | | Integration Tests | ✅ | ❌ | ❌ | | Acceptance Tests (Reqnroll) | ✅ | ❌ | ❌ | | Architecture Tests (NetArchTest) | ✅ | ❌ | ❌ | | Rate Limiting | ✅ | ✅ | ❌ | | CORS | ✅ | ✅ | ❌ | | JWT Authentication | ✅ | ✅ | ❌ | | RBAC Authorization | ✅ | ✅ | ❌ | | Multi-Tenancy Support | ✅ | ✅ | ❌ | | Feature Flags | ✅ | ✅ | ❌ | | OpenAI Integration | ❌ | ❌ | ✅ | | Semantic Kernel | ❌ | ❌ | ✅ | | Bot Framework | ❌ | ❌ | ✅ |

Code Examples: - Feature configuration examples - Optional feature inclusion - Feature toggle patterns

Diagrams: - Feature dependency graph - Optional vs. required features

Deliverables: - Complete feature catalog - Configuration guide - Feature selection matrix

CYCLE 3: ATP Service Architecture from Templates (~3,500 lines)¶

Topic 5: ATP Services Built from Microservice Template¶

What will be covered: - ATP Service Inventory

All ATP services instantiated from ConnectSoft.MicroserviceTemplate:

1. ATP.Ingestion.Service
   - Aggregate: AuditRecord
   - Persistence: NHibernate (Azure SQL)
   - Messaging: MassTransit (Azure Service Bus)
   - Actors: None
   - APIs: REST, gRPC

2. ATP.Policy.Service
   - Aggregate: PolicyDefinition, ClassificationRule, RetentionPolicy
   - Persistence: NHibernate (Azure SQL)
   - Messaging: MassTransit
   - Actors: None
   - APIs: REST, gRPC

3. ATP.Integrity.Service
   - Aggregate: IntegrityCheckpoint, HashChain, MerkleTree
   - Persistence: NHibernate (Azure SQL) + Cosmos DB (for proofs)
   - Messaging: MassTransit
   - Actors: None
   - APIs: REST, gRPC

4. ATP.Projection.Service
   - Aggregate: ProjectionWatermark
   - Persistence: NHibernate (Azure SQL for read models)
   - Messaging: MassTransit (consumer)
   - Actors: None
   - APIs: REST (admin only)

5. ATP.Query.Service
   - Aggregate: None (read-only)
   - Persistence: NHibernate (read from projections)
   - Messaging: None
   - Actors: None
   - APIs: REST, gRPC

6. ATP.Export.Service
   - Aggregate: ExportJob
   - Persistence: NHibernate (Azure SQL)
   - Messaging: MassTransit
   - Actors: None (background workers)
   - APIs: REST, gRPC

7. ATP.Search.Service (Optional)
   - Aggregate: SearchIndex
   - Persistence: Azure Cognitive Search
   - Messaging: MassTransit (indexer)
   - Actors: None
   - APIs: REST

8. ATP.Admin.Service
   - Aggregate: ConfigurationEntry, FeatureFlag
   - Persistence: NHibernate (Azure SQL)
   - Messaging: MassTransit
   - Actors: None
   - APIs: REST, gRPC

Template Instantiation Commands

# 1. Ingestion Service
dotnet new connectsoft-microservice \
    --name ConnectSoft.ATP.Ingestion \
    --AggregateRootName AuditRecord \
    --UseNHibernate true \
    --UseMassTransit true \
    --UseGrpc true \
    --UseOrleans false \
    --Docker true \
    --output ./ConnectSoft.ATP.Ingestion

# 2. Policy Service
dotnet new connectsoft-microservice \
    --name ConnectSoft.ATP.Policy \
    --AggregateRootName PolicyDefinition \
    --UseNHibernate true \
    --UseMassTransit true \
    --UseGrpc true \
    --Docker true \
    --output ./ConnectSoft.ATP.Policy

# 3. Query Service (read-only, no messaging producer)
dotnet new connectsoft-microservice \
    --name ConnectSoft.ATP.Query \
    --UseNHibernate true \
    --UseMassTransit false \
    --UseGrpc true \
    --Docker true \
    --output ./ConnectSoft.ATP.Query

Post-Instantiation Customization

After instantiation, each service is customized:

1. Rename Aggregates
   - MicroserviceAggregateRoot → AuditRecord
   - Update all references (entities, repositories, specs, DTOs)

2. Add Domain Logic
   - Implement business rules in Aggregate
   - Define Value Objects (Classification, Retention, etc.)
   - Add Domain Events (AuditRecordAppended, PolicyApplied, etc.)

3. Configure Persistence
   - Add FluentNHibernate mappings for new entities
   - Create FluentMigrator migrations
   - Add indexes for query patterns

4. Configure Messaging
   - Define message contracts (events, commands)
   - Implement consumers (event handlers)
   - Configure MassTransit routing

5. Implement API Endpoints
   - Add REST controllers
   - Add gRPC service implementations
   - Add DTO mappings

6. Add Tests
   - Unit tests for domain logic
   - Integration tests for APIs
   - Acceptance tests (Reqnroll scenarios)

7. Update Configuration
   - Add service-specific options
   - Configure health checks
   - Set up feature flags

8. Add Deployment Manifests
   - Customize Kubernetes YAML
   - Update Helm chart values
   - Add Pulumi infrastructure code

Code Examples: - Complete service instantiation commands - Post-instantiation customization script - Before/after template customization

Diagrams: - ATP services mapped to template - Customization workflow - Service interdependencies

Deliverables: - ATP service inventory - Instantiation cookbook - Customization guide

Topic 6: Shared Patterns Across ATP Services¶

What will be covered: - Common Patterns (from Template)

// 1. Tenant Context Propagation (all services)
public class TenantContextMiddleware
{
    public async Task InvokeAsync(HttpContext context)
    {
        var tenantId = ResolveTenantId(context);
        TenantContext.Current = new TenantContext(tenantId);
        await _next(context);
    }
}

// 2. Idempotency Middleware (Ingestion, Policy, Export)
public class IdempotencyMiddleware
{
    public async Task InvokeAsync(HttpContext context)
    {
        var idempotencyKey = context.Request.Headers["Idempotency-Key"];
        if (await _store.HasProcessedAsync(idempotencyKey))
        {
            return await _store.GetCachedResponseAsync(idempotencyKey);
        }
        // ... process and cache
    }
}

// 3. Outbox Pattern (all event producers)
public class OutboxPublisher : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            var unpublishedEvents = await _outboxRepo.GetUnpublishedAsync();
            foreach (var evt in unpublishedEvents)
            {
                await _bus.PublishAsync(evt);
                await _outboxRepo.MarkPublishedAsync(evt.Id);
            }
            await Task.Delay(1000, stoppingToken);
        }
    }
}

// 4. Health Checks (all services)
public void ConfigureServices(IServiceCollection services)
{
    services.AddHealthChecks()
        .AddNHibernateCheck()              // From template
        .AddMassTransitCheck()             // From template
        .AddAzureServiceBusCheck()         // From template
        .AddRedisCheck()                   // From template
        .AddCustomCheck<ServiceSpecificHealthCheck>();  // Added
}

// 5. Structured Logging (all services)
Log.Information("Processing {AggregateType} {AggregateId} for tenant {TenantId}",
    aggregate.GetType().Name, 
    aggregate.Id, 
    TenantContext.Current.TenantId);

ConnectSoft.Extensions Libraries (shared across all services)

ConnectSoft.Extensions.PersistenceModel
- IRepository<TEntity, TId>
- IUnitOfWork
- ISpecification<TEntity, TId>

ConnectSoft.Extensions.PersistenceModel.NHibernate
- GenericRepository<TEntity, TId>
- NHibernateUnitOfWork
- QueryableSpecification<TEntity, TId>

ConnectSoft.Extensions.MessagingModel
- Message base classes
- CloudEvents support
- Outbox/Inbox abstractions

ConnectSoft.Extensions.MessagingModel.MassTransit
- MassTransit configuration extensions
- Saga state machine base classes

ConnectSoft.Extensions.ObservabilityModel
- OpenTelemetry configuration
- Structured logging helpers
- Metrics and tracing utilities

Code Examples: - Shared pattern implementations - ConnectSoft.Extensions usage - Cross-cutting concerns

Diagrams: - Shared patterns across services - Extension libraries architecture

Deliverables: - Common patterns catalog - Extension libraries guide - Pattern reuse guidelines

CYCLE 4: Template Instantiation & Customization (~4,000 lines)¶

Topic 7: Creating New Services from Template¶

What will be covered: - Step-by-Step Instantiation

# Step 1: Install Template (if not already installed)
dotnet new install ConnectSoft.MicroserviceTemplate.Installer::2.5.0

# Step 2: Create Service from Template
dotnet new connectsoft-microservice \
    --name ConnectSoft.ATP.NewService \
    --AggregateRootName NewAggregate \
    --UseNHibernate true \
    --UseMassTransit true \
    --UseGrpc true \
    --UseOrleans false \
    --UseOpenAI false \
    --Docker true \
    --output ./ConnectSoft.ATP.NewService

# Step 3: Navigate to Service Directory
cd ConnectSoft.ATP.NewService

# Step 4: Restore Dependencies
dotnet restore

# Step 5: Build Solution
dotnet build

# Step 6: Run Tests
dotnet test

# Step 7: Run Service Locally
cd ConnectSoft.ATP.NewService.Application
dotnet run

# Step 8: Verify Health
curl https://localhost:7001/health

Template Parameters Explained

--name: Solution and project name prefix
- Example: ConnectSoft.ATP.Ingestion
- Affects: All project names, namespaces, assembly names

--AggregateRootName: Primary domain entity name
- Example: AuditRecord
- Affects: Entity classes, repositories, specifications, DTOs

--UseNHibernate: Include NHibernate ORM
- true: Adds NHibernate projects, mappings, migrations
- false: Uses in-memory or custom persistence

--UseMassTransit: Include MassTransit messaging
- true: Adds MassTransit, Azure Service Bus, outbox/inbox
- false: No messaging infrastructure

--UseNServiceBus: Include NServiceBus (alternative to MassTransit)
- true: Adds NServiceBus, outbox/inbox
- false: Use MassTransit or no messaging

--UseGrpc: Include gRPC service
- true: Adds Grpc.AspNetCore, proto files, service implementations
- false: REST API only

--UseGraphQL: Include GraphQL API
- true: Adds Hot Chocolate, schema definitions
- false: REST/gRPC only

--UseOrleans: Include Microsoft Orleans actor model
- true: Adds Orleans, grains, silos, clustering
- false: No actor model

--UseDapr: Include Dapr actors/state
- true: Adds Dapr SDK, actor interfaces
- false: No actor model

--UseMongoDb: Include MongoDB persistence
- true: Adds MongoDB.Driver, repositories
- false: Use NHibernate or custom

--UseOpenAI: Include OpenAI integration
- true: Adds OpenAI SDK, prompts, embeddings
- false: No AI features

--UseSemanticKernel: Include Semantic Kernel
- true: Adds Semantic Kernel, plugins, planners
- false: No AI orchestration

--Docker: Include Docker support
- true: Adds Dockerfile, docker-compose, K8s manifests
- false: No containerization

Automated Customization Script

# customize-service.ps1
param(
    [string]$ServiceName,
    [string]$AggregateName,
    [string]$SolutionPath
)

Write-Host "Customizing $ServiceName..."

# 1. Rename projects (if needed)
Get-ChildItem -Path $SolutionPath -Recurse -Filter "*.csproj" | ForEach-Object {
    $content = Get-Content $_.FullName -Raw
    $content = $content -replace "MicroserviceTemplate", $ServiceName
    Set-Content $_.FullName -Value $content
}

# 2. Rename aggregate references
Get-ChildItem -Path $SolutionPath -Recurse -Include "*.cs" | ForEach-Object {
    $content = Get-Content $_.FullName -Raw
    $content = $content -replace "MicroserviceAggregateRoot", $AggregateName
    Set-Content $_.FullName -Value $content
}

# 3. Update configuration files
Get-ChildItem -Path $SolutionPath -Recurse -Filter "appsettings*.json" | ForEach-Object {
    $json = Get-Content $_.FullName | ConvertFrom-Json
    $json.ApplicationName = $ServiceName
    $json | ConvertTo-Json -Depth 10 | Set-Content $_.FullName
}

# 4. Initialize Git repository
Push-Location $SolutionPath
git init
git add .
git commit -m "Initial commit from ConnectSoft.MicroserviceTemplate"
Pop-Location

Write-Host "Customization complete!"

Code Examples: - Complete instantiation workflow - Parameter selection guide - Automated customization scripts

Diagrams: - Instantiation workflow - Parameter decision tree - Customization pipeline

Deliverables: - Instantiation guide - Parameter reference - Automation scripts

Topic 8: Advanced Template Customization¶

What will be covered: - Domain Model Customization

// Before (template default):
public class MicroserviceAggregateRoot : IAggregateRoot<Guid>
{
    public Guid Id { get; protected set; }
    // ...
}

// After (ATP customization):
public class AuditRecord : IAggregateRoot<string>
{
    public string Id { get; protected set; }  // ULID
    public string TenantId { get; protected set; }
    public DateTime OccurredAtUtc { get; protected set; }
    public Actor Actor { get; protected set; }
    public Resource Resource { get; protected set; }
    public string Action { get; protected set; }
    public Classification Classification { get; protected set; }
    public RetentionPolicy Retention { get; protected set; }

    // Business methods
    public void Classify(ClassificationRule rule) { /* ... */ }
    public void Redact(RedactionPolicy policy) { /* ... */ }
    public void ApplyRetention(RetentionPolicy policy) { /* ... */ }
}

Persistence Customization
Add custom mappings
Create migrations
Add indexes
Configure second-level cache
Messaging Customization
Define message contracts
Implement consumers
Add saga state machines
Configure retry policies
API Customization
Add endpoints
Customize DTOs
Add validation
Configure Swagger
Infrastructure Customization
Add custom health checks
Configure observability
Add feature flags
Integrate with Azure services

Code Examples: - Complete customization examples (all layers) - Before/after comparisons - ATP-specific customizations

Diagrams: - Customization points - Extension points

Deliverables: - Customization guide - ATP customization patterns - Extension cookbook

CYCLE 5: Template Options & Parameters (~3,500 lines)¶

Topic 9: Template Option System¶

What will be covered: - How Template Options Work - .NET Template Engine symbol resolution - Conditional compilation (#if, #else, #endif) - File/folder inclusion/exclusion based on options - Text replacement (SourceName → TargetName)

All Template Options Reference (Complete documentation of every option, its effect, and when to use it)
Option Combinations
Valid combinations
Invalid/conflicting combinations
Recommended presets (e.g., "ATP Standard", "ATP Lite")
Custom Option Templates
Creating your own option (extending template)
Option validation

Code Examples: - template.json configuration - Option usage patterns - Validation logic

Diagrams: - Option dependency graph - Conditional inclusion flow

Deliverables: - Complete options reference - Option combination matrix - Custom option guide

Topic 10: ATP Template Presets¶

What will be covered: - Predefined Configurations for ATP

# ATP Standard Service (typical)
dotnet new connectsoft-microservice \
    --name ConnectSoft.ATP.MyService \
    --UseNHibernate true \
    --UseMassTransit true \
    --UseGrpc true \
    --UseOrleans false \
    --Docker true

# ATP Read-Only Service (Query, Search)
dotnet new connectsoft-microservice \
    --name ConnectSoft.ATP.QueryService \
    --UseNHibernate true \
    --UseMassTransit false \
    --UseGrpc true \
    --Docker true

# ATP Worker Service (Projection, Export)
dotnet new connectsoft-microservice \
    --name ConnectSoft.ATP.ProjectionWorker \
    --UseNHibernate true \
    --UseMassTransit true \
    --UseGrpc false \
    --Docker true

Preset Scripts
Create presets as PowerShell/Bash scripts
Version-controlled templates
Team-wide consistency

Code Examples: - Preset definitions - Preset instantiation scripts

Deliverables: - ATP preset catalog - Instantiation scripts - Preset selection guide

CYCLE 6: Shared Libraries & Extensions (~3,000 lines)¶

Topic 11: ConnectSoft.Extensions Library Ecosystem¶

What will be covered: - Complete Extensions Catalog

ConnectSoft.Extensions.PersistenceModel
- Repository pattern abstractions
- Unit of Work pattern
- Specification pattern

ConnectSoft.Extensions.PersistenceModel.NHibernate
- NHibernate implementations
- FluentNHibernate helpers
- Query builders

ConnectSoft.Extensions.PersistenceModel.MongoDb
- MongoDB implementations
- Document query builders

ConnectSoft.Extensions.MessagingModel
- Message abstractions
- CloudEvents support
- Outbox/Inbox interfaces

ConnectSoft.Extensions.MessagingModel.MassTransit
- MassTransit integration
- Saga helpers
- Consumer conventions

ConnectSoft.Extensions.ObservabilityModel
- OpenTelemetry setup
- Structured logging
- Metrics and traces

ConnectSoft.Extensions.SecurityModel
- JWT validation
- RBAC/ABAC policies
- Tenant isolation

ConnectSoft.Extensions.ConfigurationModel
- Options pattern helpers
- Azure Key Vault integration
- Configuration validation

How ATP Uses Extensions
All services reference ConnectSoft.Extensions.*
Consistent patterns across services
Version management
Creating Custom Extensions
When to create a new extension library
How to structure
Publishing to Azure Artifacts

Code Examples: - Extensions usage in ATP services - Custom extension creation

Diagrams: - Extensions library architecture - Dependency graph

Deliverables: - Extensions catalog - Usage guide - Custom extension guide

Topic 12: Shared ATP Libraries¶

What will be covered: - ATP-Specific Shared Libraries

ConnectSoft.ATP.Core
- Shared domain models (Actor, Resource, Classification, Retention)
- Common value objects
- Shared interfaces

ConnectSoft.ATP.Contracts
- Message contracts (events, commands)
- DTO definitions
- API contracts

ConnectSoft.ATP.Client
- Service agent clients (REST, gRPC)
- Retry policies
- Circuit breakers

ConnectSoft.ATP.Extensions
- ATP-specific extension methods
- Helper utilities
- Common middleware

Library Creation from Template

dotnet new connectsoft-library \
    --name ConnectSoft.ATP.Core \
    --output ./ConnectSoft.ATP.Core

Code Examples: - Shared library structure - Library instantiation - Cross-service usage

Diagrams: - Shared libraries architecture

Deliverables: - Shared library catalog - Creation guide - Usage patterns

CYCLE 7: API Gateway Template Integration (~3,000 lines)¶

Topic 13: ATP Gateway from Gateway Template¶

What will be covered: - Gateway Template Structure - YARP reverse proxy configuration - Authentication/Authorization - Rate limiting - Routing rules - Tenant resolution

ATP Gateway Instantiation

dotnet new connectsoft-gateway \
    --name ConnectSoft.ATP.Gateway \
    --UseYarp true \
    --UseOcelot false \
    --Docker true \
    --output ./ConnectSoft.ATP.Gateway

Gateway Configuration
Service discovery
Load balancing
Circuit breakers
Observability integration

Code Examples: - Gateway configuration - Routing rules - Custom middleware

Diagrams: - Gateway architecture - Request flow

Deliverables: - Gateway setup guide - Configuration reference - ATP gateway patterns

Topic 14: Gateway-Service Integration¶

What will be covered: - Service Registration - API Versioning - Authentication Flow - Rate Limiting Policies - Tenant Routing

Code Examples: - Service registration - API versioning configuration - Multi-tenant routing

Diagrams: - Gateway-service integration - Authentication flow

Deliverables: - Integration guide - Routing patterns - Security configuration

CYCLE 8: Library Template Usage (~2,500 lines)¶

Topic 15: Creating Shared Libraries¶

What will be covered: - Library Template Instantiation - Library Structure - NuGet Packaging - Versioning Strategy - Publishing to Azure Artifacts

Code Examples: - Library creation - NuGet configuration - Publishing scripts

Deliverables: - Library creation guide - Publishing workflow

Topic 16: API Library Template for Client SDKs¶

What will be covered: - API Client Generation - Service Agent Pattern - Retry/Circuit Breaker Policies - Client Configuration

Code Examples: - Client SDK generation - Usage examples

Deliverables: - SDK creation guide - Client usage guide

CYCLE 9: Blazor & Frontend Templates (~3,000 lines)¶

Topic 17: Blazor Component Library¶

What will be covered: - Component Library Template - ATP UI Components - Design System Integration - Component Testing

Code Examples: - Component creation - Usage in applications

Deliverables: - Component library guide - ATP component catalog

Topic 18: Blazor Microfrontend & Shell¶

What will be covered: - Microfrontend Architecture - Shell Application - Module Federation - Cross-Module Communication

Code Examples: - Microfrontend setup - Shell configuration

Deliverables: - Microfrontend guide - ATP admin portal architecture

CYCLE 10: Platform & Identity Templates (~2,500 lines)¶

Topic 19: Identity Server Template¶

What will be covered: - OAuth2/OIDC Server Setup - ATP Identity Service - Multi-Tenant Identity - SSO Integration

Code Examples: - Identity server configuration

Deliverables: - Identity setup guide

Topic 20: Platform Template¶

What will be covered: - Complete Platform Architecture - Multi-Service Orchestration - Shared Infrastructure

Code Examples: - Platform instantiation

Deliverables: - Platform guide

CYCLE 11: Template Packaging & Distribution (~3,000 lines)¶

Topic 21: NuGet Template Packaging¶

What will be covered: - Template .nuspec File - Package Structure - Build Pipeline for Templates - Publishing to NuGet.org vs. Azure Artifacts

Code Examples: - nuspec configuration - Build scripts

Deliverables: - Packaging guide - Publishing workflow

Topic 22: Template Versioning¶

What will be covered: - Semantic Versioning for Templates - Breaking vs. Non-Breaking Changes - Changelog Management - Deprecation Strategy

Code Examples: - Version management

Deliverables: - Versioning guide - Changelog conventions

CYCLE 12: Template Versioning & Updates (~3,000 lines)¶

Topic 23: Template Lifecycle Management¶

What will be covered: - Template Versioning Strategy - Update Propagation - Breaking Changes - Migration Guides

Code Examples: - Update procedures - Migration scripts

Deliverables: - Lifecycle management guide - Update automation

Topic 24: Upgrading Services from Old Templates¶

What will be covered: - Upgrade Assessment - Automated Upgrade Tools - Manual Migration Steps - Testing Upgraded Services

Code Examples: - Upgrade scripts - Testing procedures

Deliverables: - Upgrade guide - Compatibility matrix

CYCLE 13: CI/CD Pipeline Integration (~3,500 lines)¶

Topic 25: Azure Pipeline Templates¶

What will be covered: - Reusable Pipeline Templates - Build Stage Template - Test Stage Template - Deploy Stage Template - Quality Gate Template

Code Examples: - Complete pipeline templates - Usage in services

Deliverables: - Pipeline template library - Integration guide

Topic 26: GitOps Integration¶

What will be covered: - Template-Generated Manifests - FluxCD/ArgoCD Integration - Automated Deployments

Code Examples: - GitOps configuration

Deliverables: - GitOps setup guide

CYCLE 14: Template Testing & Validation (~2,500 lines)¶

Topic 27: Template Quality Assurance¶

What will be covered: - Template Testing Strategy - Instantiation Tests - Build Tests - Validation Rules

Code Examples: - Test automation

Deliverables: - Testing guide - Validation framework

Topic 28: Template Validation Tools¶

What will be covered: - Automated Validation - Linting Rules - Security Scanning

Code Examples: - Validation scripts

Deliverables: - Validation tools - Quality gates

CYCLE 15: Template Governance & Best Practices (~3,000 lines)¶

Topic 29: Template Governance¶

What will be covered: - Template Standards - Review Process - Approval Workflow - Template Registry

Code Examples: - Governance policies

Deliverables: - Governance guide - Standards document

Topic 30: Best Practices¶

What will be covered: - Template Design Principles - Common Pitfalls - Performance Optimization - Security Best Practices

Code Examples: - Best practice examples

Deliverables: - Best practices handbook - Anti-patterns guide

CYCLE 16: AI-Powered Template Generation (~3,000 lines)¶

Topic 31: ConnectSoft Software Factory Integration¶

What will be covered: - Autonomous Template Instantiation - AI Agents Creating Services - Template Selection Logic - Customization Automation

Code Examples: - AI agent workflows

Deliverables: - AI integration guide

Topic 32: Template Evolution with AI¶

What will be covered: - AI-Driven Template Improvements - Pattern Recognition - Automated Refactoring - Future of Templates

Code Examples: - AI-powered tools

Deliverables: - AI roadmap - Future directions

Summary of Deliverables¶

Across all 16 cycles, this documentation will provide:

Template Ecosystem
Complete ConnectSoft template catalog
Template philosophy and principles
ATP template usage matrix
Microservice Template
Deep architecture dive
All ATP services from template
Shared patterns across services
Instantiation & Customization
Step-by-step creation guide
Parameter reference
Advanced customization techniques
ATP presets
Shared Components
ConnectSoft.Extensions libraries
ATP shared libraries
Extension creation guide
Specialized Templates
API Gateway template usage
Library templates
API Library templates
Blazor templates (components, microfrontends, shell)
Platform and Identity templates
Packaging & Distribution
NuGet template packaging
Azure Artifacts publishing
Template versioning
Distribution workflows
Template Lifecycle
Version management
Update propagation
Service upgrades
Migration guides
CI/CD Integration
Pipeline templates
GitOps manifests
Automated deployments
Quality Assurance
Template testing strategies
Validation tools
Quality gates
Governance & Best Practices
- Template standards
- Review processes
- Best practices handbook
- Anti-patterns catalog
AI Integration
- Software Factory integration
- Autonomous template usage
- Future AI-powered template evolution

Microservice Template Documentation: Template-specific guides
Clean Architecture: ATP architecture overview
DDD Patterns: Domain-driven design in ATP
Persistence: Data access patterns
Messaging: Event-driven patterns
CI/CD: Deployment automation
Testing Strategy: Comprehensive testing
Configuration: Service configuration

This documentation plan covers complete template integration for ATP, from understanding the ConnectSoft template ecosystem and instantiating services to customizing implementations, managing shared libraries, leveraging specialized templates, packaging and distributing templates, handling lifecycle and updates, integrating CI/CD pipelines, ensuring quality, establishing governance, and embracing AI-powered template generation for consistent, high-quality, and rapidly evolvable service development.