🧩 ConnectSoft Microservice Template¶

🚀 Introduction¶

The ConnectSoft Microservice Template is a modular, scalable, and AI-integrated foundation for building cloud-native microservices. It empowers both humans and autonomous agents to generate, extend, and operate services that align with modern SaaS, DDD, Clean Architecture, and event-driven patterns — out of the box.

Whether you're building a single aggregate service or orchestrating thousands of AI-generated components, this template is the launchpad for fully traceable, observable, and secure backend systems.

🎯 Purpose¶

The ConnectSoft Microservice Template enables the rapid, scalable, and intelligent creation of production-grade microservices. It’s designed for both:

🤖 Autonomous agents in the ConnectSoft AI Software Factory
👨‍💻 Human developers building enterprise, cloud-native solutions

The template scaffolds a multi-project solution that embodies:

✅ Domain-Driven Design (DDD)
✅ Clean Architecture principles
✅ Event-Driven Messaging
✅ Modular runtime options
✅ Secure, observable, testable microservices

💡 It serves as the core automation blueprint for all ConnectSoft-generated services and is used at scale to create thousands of independently deployed modules.

🧱 Architectural Foundations¶

Paradigm	Support
Domain-Driven Design	✅ Aggregates, Entities, Events, Repositories, Specs
Clean Architecture	✅ Structured layering: Domain → Application → Infrastructure → API
Event-Driven Architecture	✅ MassTransit / NServiceBus, pub-sub, outbox
Actor-Based Models	✅ Orleans, Dapr, Akka
Serverless Models	✅ Azure Functions
Modular APIs	✅ REST, gRPC, GraphQL, SignalR
AI Integration	✅ Semantic Kernel, OpenAI, Bot Framework
Infrastructure as Code	✅ Pulumi (Azure-first), Docker, Kubernetes

🧬 Composition & Solution Structure¶

Each generated service consists of 35+ modular projects, grouped by responsibility:

📦 Domain/
    ├── EntityModel/
    ├── DomainModel/
    └── DomainModel.Impl/

📦 Persistence/
    ├── PersistenceModel/
    ├── NHibernate / MongoDb/
    └── Migrations/

📦 Messaging/
    ├── MessagingModel/
    └── FlowModel.[NServiceBus|MassTransit]/

📦 ServiceModel/
    ├── RestApi / Grpc / GraphQL / SignalR / AzureFunction
    └── CoreWCF / ServiceFabric (optional)

📦 ActorModel/
    ├── Orleans / Dapr / Akka

📦 SchedulerModel/
    ├── Hangfire / Quartz

📦 AI/
    └── SemanticKernel/

📦 Bot/
    └── BotModel/

📦 Common/
    ├── Options/
    ├── Metrics/
    └── Core/

📦 Application/
    ├── ApplicationModel/
    └── Application (host)

📦 Infrastructure/
    ├── DockerCompose/
    └── InfrastructureModel/ (Pulumi)

📦 Testing/
    ├── UnitTests/
    ├── AcceptanceTests/
    └── ArchitectureTests/

📦 Architecture/
    ├── ArchitectureModel/
    └── DiagramAsCodeModel/

✅ Fully aligned to AI-assisted orchestration, CI/CD automation, and cross-platform deployments.

🧠 Generator & Automation Flow¶

flowchart TD
    VisionAgent --> ApplicationArchitectAgent
    ApplicationArchitectAgent --> MicroserviceGenerator
    MicroserviceGenerator -->|Uses| MicroserviceTemplate
    MicroserviceTemplate -->|Outputs| MultiProjectSolution
    MultiProjectSolution --> DevOpsPipeline
    DevOpsPipeline -->|Builds And Deploys| CloudService

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

⚙️ CLI Template Summary¶

Command	Description
`dotnet new connectsoft-microservice`	Instantiates a new microservice
`--AggregateRootName`	The name of the main entity (e.g., `Order`)
`--PersistenceModelType`	`NHibernate`, `MongoDb`, or `None`
`--MessagingModelType`	`NServiceBus`, `MassTransit`, or `None`
`--ServiceModelType`	`RestApi`, `Grpc`, `GraphQL`, `SignalR`, `AzureFunction`
`--ActorModelType`	`Orleans`, `Dapr`, `Akka`, or `None`
`--SchedulerModelType`	`Hangfire`, `Quartz`, or `None`
`--UseSemanticKernel`	Adds AI orchestration capabilities
`--UseOpenAI`	Enables OpenAI integration
`--Docker`, `--UsePulumi`	Infrastructure and deployment options
`--UseMicrosoftBotBuilder`	Adds Microsoft Bot Framework integration
`--Swagger`, `--HealthCheck`, `--CORS`, `--FeatureFlags`	Enables specific cross-cutting features

🔄 All CLI options are agent-compatible and can be dynamically toggled based on use case requirements.

🧪 Included Best Practices¶

✅ Strong layering and modularity
✅ Isolation of service concerns
✅ Environment-specific config injection
✅ Secrets management, tenant guards, authentication
✅ Observability-first (metrics, tracing, logging)
✅ Test-first development, BDD, architecture validation

✅ Summary¶

The ConnectSoft Microservice Template is the launchpad for building composable SaaS, intelligent backend systems, and domain-specific modules with:

Predictable structure
AI extensibility
Full observability
CI/CD integration
Cloud-native runtime support

⚙️ Template Generation and Parameters¶

The ConnectSoft Microservice Template is available as a reusable .NET template package, invoked via:

dotnet new connectsoft-microservice

It is designed to support:

🔁 Human developers (manual CLI generation)
🤖 ConnectSoft AI Agents (automated generation)
🧱 Highly configurable options to generate only the necessary features

✅ The template is parameterized and modular, allowing each concern (e.g., messaging, actors, service models) to be toggled on or off at generation time.

🧩 Installation and Usage¶

🔧 Install from NuGet / Azure DevOps Feed¶

dotnet new install ConnectSoft.MicroserviceTemplate::1.0.0

🚀 Generate a new service¶

dotnet new connectsoft-microservice \
  --AggregateRootName Order \
  --AggregateRootObjectId OrderId \
  --ServiceModelType RestApi \
  --PersistenceModelType NHibernate \
  --MessagingModelType NServiceBus \
  --UseOpenAI true \
  --UseSemanticKernel true

📌 Template Parameters Overview¶

Parameter	Type	Description
`--AggregateRootName`	`string`	Name of the aggregate (e.g., `Order`)
`--AggregateRootObjectId`	`string`	ID of the aggregate (e.g., `OrderId`)
`--ServiceModelType`	`choice`	`RestApi`, `Grpc`, `GraphQL`, `SignalR`, `AzureFunction`, `None`
`--PersistenceModelType`	`choice`	`NHibernate`, `MongoDb`, `None`
`--MessagingModelType`	`choice`	`NServiceBus`, `MassTransit`, `None`
`--ActorModelType`	`choice`	`Orleans`, `Dapr`, `Akka`, `None`
`--SchedulerModelType`	`choice`	`Hangfire`, `Quartz`, `None`
`--NHibernateDialectType`	`choice`	`SqlServer`, `PostgreSQL`, `MySql`
`--NHibernateSecondLevelCacheType`	`choice`	`Redis`, `None`
`--MassTransitTransport`	`choice`	`SqlServer`, `RabbitMQ`, `AzureServiceBus`
`--NServiceBusTransport`	`choice`	`SqlServer`, `RabbitMQ`
`--UseSemanticKernel`	`bool`	Adds Semantic Kernel orchestration
`--UseOpenAI`	`bool`	Enables OpenAI integrations
`--UseMicrosoftBotBuilder`	`bool`	Adds Microsoft Bot Framework entrypoints
`--UseAuditNet`	`bool`	Enables audit trail support
`--HealthCheck`, `--HealthCheckUI`	`bool`	Enables health endpoints and dashboards
`--Swagger`	`bool`	Enables Swagger / OpenAPI UI
`--Logging`	`choice`	`Serilog`, `Log4Net`, `None`
`--DistributedCache`	`choice`	`InMemory`, `Redis`, `None`
`--OpenTelemetry`	`bool`	Enables tracing, metrics, spans
`--FeatureFlags`	`bool`	Adds Microsoft.FeatureManagement
`--FeatureFlagsProvider`	`choice`	`AppSettings`, `AzureAppConfiguration`
`--AdditionalConfigurationProvider`	`choice`	`AzureAppConfiguration`, `None`
`--Docker`	`bool`	Adds Dockerfile, Docker Compose, and K8s manifests
`--UsePulumi`	`bool`	Adds Pulumi IaC infrastructure project
`--UseApplicationInsights`	`bool`	Azure App Insights support
`--CORS`	`bool`	Enables CORS middleware
`--ResourceMonitoring`	`bool`	Adds CPU/memory instrumentation
`--HttpPort` / `--HttpsPort`	`int`	Configurable port mapping
`--DatabaseName`	`string`	Primary DB name
`--NServiceBusDatabaseName`	`string`	NSB database name if selected

🔁 Conditional Inclusion¶

The template is designed with conditional project exclusion rules to optimize output:

🚫 If --MessagingModelType is None, messaging folders and config are omitted
🧠 If --UseSemanticKernel false, AI orchestration layers are skipped
🐳 If --Docker false, no Dockerfile or Compose manifests are included
🎭 If --ServiceModelType is None, no API projects are generated

This results in a minimal, purpose-driven solution, free of unused folders or dependencies.

🧠 AI-Driven Parameter Selection¶

When executed by ConnectSoft agents, parameters are automatically inferred from:

DomainModel.yaml → aggregate root and object ID
SystemArchitectureBlueprint → messaging, actor, service, scheduler selections
UseCaseBlueprint.json → triggers API, function, or message handler types
EditionMetadata → feature flag inclusion (e.g., AI, audit, bot)

📦 Output Example (when fully enabled)¶

ConnectSoft.MyService/
├── ApplicationModel/
├── Application/
├── DomainModel/
├── EntityModel/
├── MessagingModel/
├── FlowModel.MassTransit/
├── PersistenceModel/
├── PersistenceModel.NHibernate/
├── DatabaseModel.Migrations/
├── ServiceModel.RestApi/
├── SchedulerModel.Hangfire/
├── ActorModel.Orleans/
├── SemanticKernel/
├── BotModel/
├── DockerCompose/
├── InfrastructureModel/
└── UnitTests, AcceptanceTests, ArchitectureTests/

✅ Summary¶

Supports dozens of composable parameters
Output is modular, minimal, and runtime-configurable
Fully aligned with agentic generation and manual CLI workflows
Enables clean automation, feature toggling, and extension-by-design

🧱 Supported Architectures and Runtime Models¶

The ConnectSoft Microservice Template is engineered to support multiple architectural styles and execution runtimes. This makes it suitable for a wide range of modern SaaS, enterprise, and AI-powered systems — from domain-oriented REST services to actor-based real-time systems, background jobs, and serverless tasks.

🧱 Clean Architecture¶

The solution is built with strict separation of concerns across well-defined layers:

flowchart TD
  UI[ServiceModel Layer - REST/gRPC/GraphQL] --> Domain[DomainModel + EntityModel]
  Domain --> Infra[Infrastructure + Persistence]

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

Layer	Role
DomainModel	Encapsulates core business logic, aggregates, and events
ApplicationModel	Coordinates use cases, handles cross-cutting concerns
ServiceModel	Interface adapters: REST, gRPC, GraphQL, SignalR
PersistenceModel	Abstract data access (SQL, NoSQL)
PersistenceModel.[NHibernate/MongoDB]	Real implementations (e.g., NHibernate, MongoDB, Dapper)

✅ The domain model never references infrastructure such as(NHibernate/MongoDB), enforcing inward dependency flow.

🧠 Domain-Driven Design (DDD)¶

The template is deeply aligned with DDD tactical patterns, supporting:

✅ Aggregate roots, entities and domain events
✅ Value objects and enumerations
✅ Domain services and factories
✅ Ubiquitous language and modeling boundaries
✅ Specifications and queries

🔄 Domain models are split across:

Project	Role
`EntityModel`	Aggregate roots, entities, value objects
`DomainModel`	Interfaces for domain services and events
`DomainModel.Impl`	Implementations and validation logic

🕸️ Event-Driven Architecture (EDA)¶

Supports both MassTransit and NServiceBus for:

Domain → Integration event publishing
Pub-sub with external systems
Outbox pattern and retries
Saga orchestration and stateful flows

Transport	Saga Engine	Persistence Options
MassTransit	Yes	NHibernate, MongoDB, CosmosDB, Dapper
NServiceBus	Yes	SQL, MongoDB, CosmosDB

📦 Messaging is modular via:

MessagingModel
FlowModel.MassTransit or FlowModel.NServiceBus

🧠 Actor Model Support¶

Supports virtual actor systems for distributed, stateful logic.

Framework	Project
Orleans	`ActorModel.Orleans`
Dapr	`ActorModel.Dapr`
Akka.NET	`ActorModel.Akka`

Actors are fully isolated and support telemetry, AI integration, and Saga handoffs.

🔄 Background Execution Models¶

Job-based, long-running, or schedule-triggered workloads are supported via:

Runtime	Project
Hangfire	`SchedulerModel.Hangfire`
Quartz	`SchedulerModel.Quartz`
Azure Functions	`ServiceModel.AzureFunction`

🧠 All jobs can emit domain events or call use cases directly.

🌐 API Surface Options¶

The template supports 6 different service exposure modes, each swappable via parameters:

API Type	Project
REST	`ServiceModel.RestApi`
gRPC	`ServiceModel.Grpc`
GraphQL	`ServiceModel.GraphQL`
SignalR	`ServiceModel.SignalR`
Azure Functions	`ServiceModel.AzureFunction`
CoreWCF / Service Fabric	Optional add-ons

📜 Swagger and ProblemDetails are integrated for REST.
🧬 Proto files are auto-generated for gRPC.

📦 Multi-Host Runtime Models¶

The host application can run with multiple entry modes:

Mode	Purpose
REST API Host	Primary HTTP interface
gRPC Server	High-performance structured messaging
SignalR Hub	Real-time pub/sub with browser or mobile clients
Background Worker	Polling, sagas, job orchestration
Azure Functions Host	Serverless, event-driven executions
Orleans / Dapr Host	Actor-based compute node

✅ All hosts share the same domain and infrastructure model.

🧠 Semantic Kernel AI Support¶

If --UseSemanticKernel is enabled:

AI Skills are added to the application pipeline
OpenAI, Azure OpenAI, Ollama, HuggingFace connectors supported
Optional plugins: OpenAPI, Microsoft Graph, Memory, Web, Document, gRPC
Integrated actor flows and planner orchestration supported

🧠 Generated microservices become agent-compatible and language-aware.

✅ Summary¶

The ConnectSoft Microservice Template supports:

Rich architectural layering (Clean, DDD)
Modular exposure (REST/gRPC/GraphQL/SignalR)
Background and serverless compute
Messaging, eventing, actors, and jobs
AI orchestration with optional plugins
Runtime flexibility: multi-host, multi-db, multi-cloud

🏗️ Solution Structure and Project Breakdown¶

The ConnectSoft Microservice Template generates a multi-project solution, organized to enforce:

🔁 Separation of concerns
🔒 Bounded context isolation
🧩 Feature composability
🔌 Optional runtime modules

This section outlines the solution structure, including libraries, host apps, integration models, testing, and diagrams.

🗂️ Tree-Based Structure (Simplified)¶

ConnectSoft.MyService/
├── Common/
│   ├── MyService/
│   ├── MyService.Options/
│   └── MyService.Metrics/
├── Domain/
│   ├── MyService.EntityModel/
│   ├── MyService.DomainModel/
│   └── MyService.DomainModel.Impl/
├── Persistence/
│   ├── MyService.PersistenceModel/
│   ├── NHibernate/
│   ├── MongoDb/
│   └── Migrations/
├── Messaging/
│   ├── MyService.MessagingModel/
│   └── MyService.FlowModel.[MassTransit|NServiceBus]/
├── ActorModel/
│   └── MyService.ActorModel.[Orleans|Dapr|Akka]/
├── Scheduler/
│   └── MyService.SchedulerModel.[Hangfire|Quartz]/
├── ServiceModel/
│   └── MyService.ServiceModel.[RestApi|Grpc|GraphQL|SignalR|Function]/
├── AI/
│   └── MyService.SemanticKernel/
├── Bot/
│   └── MyService.BotModel/
├── Application/
│   ├── MyService.ApplicationModel/
│   └── MyService.Application/
├── Infrastructure/
│   ├── MyService.DockerCompose/
│   └── MyService.InfrastructureModel/
├── Testing/
│   ├── UnitTests/
│   ├── AcceptanceTests/
│   └── ArchitectureTests/
├── Architecture/
│   ├── ArchitectureModel/
│   └── DiagramAsCodeModel/

📦 Each folder above is a separate project, promoting modularity and enabling precise dependency management.

🧱 Core Layers¶

🔹 Common Layer¶

Project	Purpose
`MyService`	Base constants, errors, service-wide helpers
`MyService.Options`	Strongly-typed config and options pattern
`MyService.Metrics`	Prometheus/OpenTelemetry metrics definitions

🔹 Domain Layer¶

Project	Purpose
`EntityModel`	Aggregates, value objects, enums
`DomainModel`	Interfaces for use cases, services, events
`DomainModel.Impl`	FluentValidation, orchestrators, processors

🔹 Persistence Layer¶

Project	Purpose
`PersistenceModel`	Repository and specification interfaces
`PersistenceModel.NHibernate`	NHibernate mappings and implementations
`PersistenceModel.MongoDb`	Mongo-specific repository implementations
`DatabaseModel.Migrations`	FluentMigrator-based SQL migration scripts
`MongoDb.Migrations`	Optional: Mongo migration strategies

🔌 Integrations & Interfaces¶

🔹 Messaging¶

Project	Purpose
`MessagingModel`	Command, event, query contracts
`FlowModel.MassTransit`	Consumers, sagas, outbox logic
`FlowModel.NServiceBus`	NSB-specific messaging logic

🔹 Actor Model¶

Project	Purpose
`ActorModel.Orleans`	Grain interfaces, implementations, timers
`ActorModel.Dapr`	Actor registration, handlers, metadata
`ActorModel.Akka`	Akka actor tree (if enabled)

🔹 ServiceModel (API)¶

Project	Purpose
`RestApi`	REST controllers, Swagger, filters
`Grpc`	Proto files, services, interceptors
`GraphQL`	Schema, queries, mutations
`SignalR`	Hub definition and real-time endpoints
`AzureFunction`	Functions triggered by HTTP, queue, cron

🔹 Scheduler¶

Project	Purpose
`SchedulerModel.Hangfire`	Job registration, dashboards, retries
`SchedulerModel.Quartz`	Quartz.NET job logic (optional)

🔹 AI and Bot¶

Project	Purpose
`SemanticKernel`	Skills, planners, connectors, plugins
`BotModel`	Microsoft Bot Framework integration (dialogs, cards, state)

🧩 Application Layer¶

Project	Purpose
`ApplicationModel`	DI container registration, middleware, telemetry setup
`Application`	Microservice host entry point (Main method)

🏗️ Infrastructure¶

Project	Purpose
`DockerCompose`	Local multi-container orchestration
`InfrastructureModel`	Pulumi-based IaC for Azure (Key Vault, App Service, Service Bus, etc.)

✅ Testing Layer¶

Project	Type
`UnitTests`	Pure logic/unit test coverage
`AcceptanceTests`	SpecFlow + BDD integration tests
`ArchitectureTests`	Dependency flow, structure, DDD validation

🧭 Architecture & Documentation¶

Project	Purpose
`ArchitectureModel`	Mermaid/C4 diagrams, project maps
`DiagramAsCodeModel`	Python-based diagram generation (e.g., Diagrams.net or Graphviz)

🧪 Traceability and Design Discipline¶

🔎 Each concern has its own bounded project
🚫 Circular references are disallowed by structure
🧠 Agents and humans both understand and extend generated solutions
✅ Fully CI/CD-friendly, each project can be:
- Independently tested
- Versioned in NuGet feeds
- Deployed as containers

✅ Summary¶

The ConnectSoft microservice solution is structured for clarity, modularity, and scalability
Each project aligns to a DDD or Clean Architecture principle
All cross-cutting concerns and host features are optionally included based on template parameters
AI agents can reason about, extend, and deploy generated code with traceable precision

🧠 Domain Layer and DDD Foundation¶

The Domain Layer represents the core business logic of the microservice, modeled following Domain-Driven Design (DDD) principles. It is independent of infrastructure, databases, protocols, and frameworks — making it the most stable and testable part of the system.

🧱 DDD Tactical Patterns Supported¶

The template includes full support for the following tactical building blocks:

Concept	Description
Entity	Object with identity over time (e.g., `Order`, `Invoice`)
Aggregate Root	A consistency boundary containing entities and rules
Value Object	Immutable object identified by its value (e.g., `Money`, `DateRange`)
Enumeration	Domain-specific enum alternative (with behavior and metadata)
Domain Service	Stateless logic that doesn't naturally fit within an entity
Domain Event	Significant business occurrence to be published internally/externally
Specification	Encapsulated, composable business rule/query logic

📦 Projects Involved¶

Project	Description
`EntityModel`	Contains entities, aggregates, value objects, enumerations
`DomainModel`	Defines use cases, domain services, and events as interfaces
`DomainModel.Impl`	Implements domain services and validation using FluentValidation

All of these are generated when a persistence model (NHibernate or MongoDb) is selected.

📂 Folder Structure Example¶

EntityModel/
  ├── Entities/
  │   └── Order.cs
  ├── ValueObjects/
  │   └── Money.cs
  ├── Enumerations/
  │   └── OrderStatus.cs

DomainModel/
  ├── Events/
  │   └── OrderPlacedEvent.cs
  ├── Services/
  │   └── IOrderPricingService.cs
  ├── UseCases/
  │   └── IPlaceOrderHandler.cs

DomainModel.Impl/
  ├── Services/
  │   └── DefaultOrderPricingService.cs
  ├── Validators/
  │   └── PlaceOrderValidator.cs

📌 Aggregate Example¶

public class Order : AggregateRoot<Guid>
{
    private readonly List<OrderItem> _items = new();

    public CustomerId CustomerId { get; private set; }
    public OrderStatus Status { get; private set; }

    public void Place()
    {
        if (_items.Count == 0)
            throw new InvalidOperationException("Order must have at least one item.");

        Status = OrderStatus.Placed;
        AddDomainEvent(new OrderPlacedEvent(Id));
    }
}

✅ Built-in support for raising domain events from within aggregates.

📚 FluentValidation Integration¶

Every command/use case has a matching validator:

public class PlaceOrderValidator : AbstractValidator<PlaceOrderInput>
{
    public PlaceOrderValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty().WithMessage("Order must contain items.");
    }
}

Validators are automatically wired via the ApplicationModel and executed before use cases are invoked.

📤 Domain Events¶

Domain events implement IDomainEvent
Can be enriched with metadata (correlationId, source aggregate, etc.)
Published to:
- Local in-process handlers
- Outbox (via MassTransit or NServiceBus)
- External pub/sub systems

public record OrderPlacedEvent(OrderId OrderId) : IDomainEvent;

🧠 Use Case Model¶

Each use case follows a request/response pattern and is implemented as a processor/retriever interface pair:

public interface IPlaceOrderHandler : IUseCase<PlaceOrderInput, PlaceOrderOutput> { }

This pattern:

Enforces a clean application boundary
Allows injection of cross-cutting behaviors (e.g., caching, telemetry, validation)
Maps to service interfaces (REST, gRPC, GraphQL)

🔄 Specification Pattern¶

The template includes optional specification support for NHibernate/MongoDB:

public class OrdersByCustomerSpec : Specification<Order>
{
    public OrdersByCustomerSpec(CustomerId customerId)
    {
        Criteria = x => x.CustomerId == customerId;
    }
}

✅ Composable, testable query logic ✅ Automatically translated to LINQ or Mongo drivers

🧪 Testing Focus¶

Domain layer is fully testable without infrastructure
Includes:
- Aggregate behavior tests
- Validator tests
- Use case logic with mocks
- Domain event dispatching

✅ Summary¶

The Domain Layer reflects business logic only
Fully decoupled from transport, database, and hosting
Follows rich DDD tactical modeling
Easy to test, extend, and validate
Emits events, enforces invariants, and defines use case contracts

🗃️ Persistence Layer and Data Models¶

The Persistence Layer abstracts the interaction between the domain model and the underlying data storage technology. It supports both relational and non-relational databases with built-in repository patterns, specification support, and optional migration infrastructure.

✅ Cleanly separated from business logic
✅ Swap-in support for NHibernate, MongoDB, or none
✅ Optional support for second-level cache (e.g., Redis)

🧱 Core Projects¶

Project	Purpose
`PersistenceModel`	Repository contracts, specifications, queries
`PersistenceModel.NHibernate`	NHibernate-based ORM implementation
`PersistenceModel.MongoDb`	MongoDB provider (Mongo Driver + fluent mapping)
`DatabaseModel.Migrations`	SQL schema migrations using FluentMigrator
`MongoDb.Migrations`	Optional Mongo migration definitions (via `MongoDBMigrations`)

Generated based on CLI flags: --PersistenceModelType, --UseMigrations, --NHibernateDialectType

⚙️ Configuration Parameters¶

Parameter	Type	Purpose
`--PersistenceModelType`	`NHibernate`, `MongoDb`, `None`
`--NHibernateDialectType`	`SqlServer`, `PostgreSQL`, `MySQL`
`--NHibernateSecondLevelCacheType`	`Redis`, `None`
`--DatabaseName`	`string`	Used in connection string generation
`--UseMigrations`	`bool`	Enables FluentMigrator or MongoDb migrations

🧩 Repository and Specification Pattern¶

public interface IOrderRepository : IRepository<IOrder, Guid>
{
    Task<IOrder?> GetByCustomerIdAsync(CustomerId customerId, CancellationToken ct);
}

public class OrdersByCustomerSpec : Specification<IOrder, Guid>
{
    public OrdersByCustomerSpec(CustomerId customerId)
    {
        Criteria = o => o.CustomerId == customerId;
    }
}

✅ Automatically wired into NHibernate or MongoDb LINQ
✅ Keeps business logic clean
✅ Supports unit testing without actual storage

🗂️ NHibernate ORM Support¶

If --PersistenceModelType NHibernate is selected:

Fluent mappings auto-generated for aggregates and value objects
Configured using:

<hibernate-configuration>
  <session-factory>
    <property name="dialect">NHibernate.Dialect.MsSql2012Dialect</property>
    ...
  </session-factory>
</hibernate-configuration>

Optional Redis caching:

"NHibernate": {
  "SecondLevelCache": "Redis",
  "Redis": {
    "ConnectionString": "localhost:6379"
  }
}

🍃 MongoDB Support¶

If --PersistenceModelType MongoDb:

Uses native Mongo driver with fluent class mapping
Supports:
- Attribute-based index creation
- Mapping profiles per aggregate
- GridFS (optional)

🗃️ Migrations Support¶

If --UseMigrations true:

Tech	Tool
SQL DBs	FluentMigrator (table/index scripts)
MongoDB	MongoDBMigrations (collection creation, seeders)

🔄 Migrations run automatically on app startup (optional environment guards)

🧪 Testing Utilities¶

In-memory NHibernate database with SQLite for local/unit tests
Mongo memory test cluster (optional)
Database mocking abstractions available via interface injection

🧠 AI Usage¶

Agents receive mappings from EntityModel to generate NHibernate/Mongo mappings
Event sourcing support is future-compatible (TBD via feature flag)
Generated specifications and repository interfaces help agents understand query models

✅ Summary¶

Supports relational and NoSQL persistence via NHibernate and MongoDB
Aligned with repository and specification patterns
Optional support for migrations, second-level cache, and audit
Cleanly isolated from domain logic — pluggable and testable
Used by both developers and generation agents to extend or scaffold features

📡 Messaging Layer and Event-Driven Patterns¶

The Messaging Layer enables microservices to communicate asynchronously through events, commands, and queries, supporting:

✅ Event-Driven Architecture (EDA)
✅ Domain Event Publishing
✅ Sagas and Process Managers
✅ Integration with external systems
✅ Outbox pattern and retries

The messaging model is pluggable, allowing use of MassTransit or NServiceBus, or disabling messaging entirely.

📦 Core Projects¶

Project	Purpose
`MessagingModel`	Contracts (commands, events, queries)
`FlowModel.MassTransit`	Consumers, publishers, outbox, saga logic
`FlowModel.NServiceBus`	Endpoint configuration, handlers, saga logic

⚙️ Template Parameters¶

Parameter	Description
`--MessagingModelType`	`MassTransit`, `NServiceBus`, `None`
`--MassTransitTransport`	`SqlServer`, `RabbitMQ`, `AzureServiceBus`
`--MassTransitPersistence`	`NHibernate`, `MongoDB`, `CosmosDB`, `Dapper`
`--NServiceBusTransport`	`SqlServer`, `RabbitMQ`
`--NServiceBusPersistence`	`SQL`, `MongoDB`, `CosmosDB`
`--UseOutboxPattern`	Implicit for both bus options
`--NServiceBusEndpointName`	Used to configure endpoint routing

🧩 Messaging Model Structure¶

📂 MessagingModel/¶

Commands/
  └── CreateOrderCommand.cs
Events/
  └── OrderPlacedEvent.cs
Queries/
  └── GetOrderDetailsQuery.cs

All contracts implement marker interfaces:

ICommand<TResponse>
IEvent
IQuery<TResponse>

🔁 MassTransit Flow Model¶

✅ Features:¶

Built-in support for:
- Consumers and message pipelines
- Saga state machines
- Retry policies
- Outbox pattern
Transport abstraction for:
- RabbitMQ
- Azure Service Bus
- SQL Server
Persistence:
- NHibernate, MongoDB, CosmosDB

public class OrderCreatedConsumer : IConsumer<OrderCreatedEvent>
{
    public async Task Consume(ConsumeContext<OrderCreatedEvent> context)
    {
        // handle event
    }
}

🧰 Configuration via `MassTransitOptions`¶

📦 NServiceBus Flow Model¶

✅ Features:¶

Endpoint orchestration with:
- Command handlers
- Event handlers
- Saga orchestration
Full compatibility with:
- SQL, CosmosDB, MongoDB persistence
- SQL Server or RabbitMQ transports
Health checks and heartbeat support
Built-in retries, dead-letter queues, metrics

public class OrderCreatedHandler : IHandleMessages<OrderCreatedEvent>
{
    public Task Handle(OrderCreatedEvent message, IMessageHandlerContext context)
    {
        // business logic
        return Task.CompletedTask;
    }
}

Configuration via NServiceBusOptions + License.xml is automated.

🧠 Domain Event Integration¶

All domain events raised from aggregates (in EntityModel) are:

Captured via IDomainEvent
Dispatched to messaging layer via internal IEventPublisher
Published through bus to external systems

✅ Enables internal decoupling + external integration

🔁 Saga Orchestration¶

Long-running workflows can be modeled using:

Feature	MassTransit	NServiceBus
State Machines	✅	✅
Correlation	✅	✅
Timeout messages	✅	✅
Storage	NHibernate, MongoDb, Cosmos	SQL, MongoDb, Cosmos

Optional saga examples included:

OrderCheckoutSaga
PaymentProcessingSaga

🧪 Testing Support¶

In-memory transport for unit/integration tests
WireMock or message spies supported
Use Harness in MassTransit or TestingContext in NSB

🧠 AI Agent Compatibility¶

Messaging model is generated dynamically by:

Extracting contract info from DomainModel.yaml
Mapping events to handlers or external subscribers
Injecting message schema metadata for AI-aware routing

✅ Summary¶

Supports both MassTransit and NServiceBus
Enables full EDA and saga orchestration
All messages follow contract-first design
Domain events are auto-published
Configurable transports and persistence per service
Includes outbox, DLQ, and retry mechanisms

🌐 Service Model and API Interfaces¶

The ServiceModel layer exposes the microservice's public API using various protocols and interfaces. Each model is generated based on the selected --ServiceModelType and follows Clean Architecture by mapping external requests to internal use cases.

📦 Supported API Models¶

API Type	Project	Description
REST API	`ServiceModel.RestApi`	Controller-based routing using ASP.NET Core
gRPC	`ServiceModel.Grpc`	Proto-defined services with support for interceptors
GraphQL	`ServiceModel.GraphQL`	HotChocolate-powered schema-first APIs
SignalR	`ServiceModel.SignalR`	Real-time bi-directional streaming
Azure Functions	`ServiceModel.AzureFunction`	Event-driven, serverless handlers
CoreWCF	`ServiceModel.CoreWCF`	WCF compatibility layer (optional)
Service Fabric	`ServiceModel.ServiceFabric`	Stateful service model (optional)

⚙️ Template Parameters¶

Parameter	Options
`--ServiceModelType`	`RestApi`, `Grpc`, `GraphQL`, `SignalR`, `AzureFunction`, `None`
`--Swagger`	Enables Swagger/OpenAPI for REST
`--CORS`	Enables Cross-Origin Resource Sharing
`--HttpPort` / `--HttpsPort`	Custom port binding in `launchSettings.json`

🔁 Clean Entry Point Mapping¶

All service models map to use case handlers defined in DomainModel:

public interface IPlaceOrderHandler : IUseCaseHandler<PlaceOrderInput, OrderDto> { }

These handlers are called from controllers, gRPC services, or function triggers depending on interface.

🌍 REST API¶

📂 Structure¶

ServiceModel.RestApi/
  ├── Controllers/
  │   └── OrdersController.cs
  ├── Filters/
  ├── Swagger/

Uses minimal or standard controllers ([ApiController])
Integrated with:
- ProblemDetails middleware
- FluentValidation (in domain services)
- AutoMapper (via profile scanning)

✅ Swagger UI at /swagger ✅ API versioning supported

⚡ gRPC API¶

📂 Structure¶

ServiceModel.Grpc/
  ├── Protos/
  │   └── order_service.proto
  ├── Services/
  │   └── OrderService.cs

Implements Grpc.Core.Server registration
Adds:
- Logging interceptor
- Validation interceptor
- Rich error details (RFC standard support)

✅ Used for low-latency messaging between services ✅ Supports unary, streaming, and bidirectional RPC

🔎 GraphQL API¶

📂 Structure¶

ServiceModel.GraphQL/
  ├── Schema/
  │   └── OrderType.cs
  ├── Queries/
  ├── Mutations/

Powered by HotChocolate
Schema-first or code-first support
Complex filtering, paging, federation-ready

✅ Easily maps to domain queries ✅ Exposes introspection endpoints

📡 SignalR (Real-Time)¶

📂 Structure¶

ServiceModel.SignalR/
  ├── Hubs/
  │   └── OrderHub.cs

Implements typed hubs
Integrated with:
- Auth (JWT)
- Multi-tenant channeling
- Live updates via internal events

✅ Used for dashboards, UI notifications, or agent callbacks

☁️ Azure Function Host¶

📂 Structure¶

ServiceModel.AzureFunction/
  ├── HttpTriggers/
  ├── QueueTriggers/
  ├── TimerTriggers/

Serverless compute model
Maps use cases to:
- REST-like endpoints
- Timer-based schedulers
- Queue/bus subscribers

✅ Enables cost-efficient, scalable, event-driven APIs

🛡️ Cross-Cutting Features¶

Feature	Description
CORS	Auto-configured via `CorsExtensions`
Authentication	JWT bearer validation with role/policy guards
ProblemDetails	RFC 7807-compliant error responses
Swagger UI	REST-only – interactive docs
Validation	FluentValidation auto-wiring for request models

🧪 Testing Support¶

REST: Testable via HTTP clients (e.g., WebApplicationFactory)
gRPC: GrpcChannel and in-memory server options
GraphQL: Unit test resolvers
Azure Functions: Durable functions integration test kits

🧠 Agent Integration¶

AI agents extract all use case entrypoints and infer:
- Required inputs
- Contracts and DTOs
- Invocation routes for bots or orchestrators

✅ Supports skill scaffolding for Semantic Kernel agents ✅ Compatible with BotFramework conversation handlers

✅ Summary¶

Supports multiple service interface models
Each API layer maps cleanly to domain use cases
Auto-wired middleware for security, validation, telemetry
REST, gRPC, GraphQL, SignalR, Functions all align to the same domain

🧠 Actor Model Integration and Virtual Actors¶

The ActorModel layer supports stateful, distributed, and concurrent logic using virtual actor patterns. Actors encapsulate behavior + state and can operate independently, making them ideal for:

Real-time collaborative applications
Distributed task orchestration
AI skill execution
Stateful workflows and domain boundaries

🔁 Supported Actor Models¶

Framework	Project	Description
Orleans	`ActorModel.Orleans`	Microsoft virtual actor framework for .NET
Dapr	`ActorModel.Dapr`	Sidecar-based actor runtime with state API
Akka.NET	`ActorModel.Akka`	Classic message-based actors (optional)

📌 Only one model is included based on the --ActorModelType parameter:

Orleans, Dapr, Akka, or None

⚙️ Template Parameters¶

Parameter	Description
`--ActorModelType`	Selects the actor model: `Orleans`, `Dapr`, `Akka`, `None`
`--UseOpenAI`	Enables actor-based AI skill execution
`--UseSemanticKernel`	Allows actor-triggered semantic orchestration

🧱 Orleans Actor Model¶

📂 Structure¶

ActorModel.Orleans/
  ├── Grains/
  │   └── IOrderGrain.cs
  │   └── OrderGrain.cs
  ├── Timers/
  └── Extensions/

Feature	Description
Virtual actor lifecycle	No explicit activation or deactivation
Timers/reminders	Built-in retry and scheduling support
Built-in clustering	Azure, Redis, ADO.NET, local
Telemetry hooks	OpenTelemetry spans, tags, grains

✅ Auto-registered via OrleansExtensions.cs ✅ Full support for stream-based messaging

🌊 Dapr Actor Model¶

📂 Structure¶

ActorModel.Dapr/
  ├── Actors/
  │   └── OrderActor.cs
  ├── Interfaces/
  │   └── IOrderActor.cs

Feature	Description
Cross-language actors	API-based actor runtime
State management	Key-value with state stores (Redis, Cosmos, etc.)
Hosted with sidecar	Dapr sidecar handles registration
Pub/Sub + secrets	Easily combined with Dapr messaging patterns

✅ Registered via Dapr component manifest ✅ Actor timers, state APIs exposed via HTTP/gRPC

🎭 Akka.NET Actor Model (Optional)¶

Feature	Description
Classic actor model	Mailbox, supervision, hierarchies
More complex patterns	Sharding, persistence, FSM
Less integrated with .NET ecosystem	Used only for specialized cases

🔌 Common Features for All Actor Models¶

✅ AI orchestration (each actor can invoke Semantic Kernel skills)
✅ Message dispatch via event bus or direct HTTP
✅ Actor health probes and logging integration
✅ Multi-tenant context propagation (e.g., TenantId, CorrelationId)

🧠 Sample Grain Contract (Orleans)¶

public interface IBankAccountGrain : IGrainWithStringKey
{
    Task Deposit(decimal amount);
    Task Withdraw(decimal amount);
    Task<decimal> GetBalance();
}

🗂️ Use Cases Examples Enabled¶

BankAccountGrain with deposit/withdraw
AI TaskGrain for Semantic Kernel orchestration
DocumentWorkflowGrain for long-running approval
ChatSessionGrain for real-time Bot integration

🧪 Testing¶

Orleans test cluster (in-memory)
Dapr test host and mocked sidecar
Actor messaging tested with BDD + ScenarioContext

🧠 Agent Integration¶

Agents use ActorModel.yaml or DomainModel.yaml to:
- Generate new grains/actors
- Inject actor logic into workflows
- Map actor interfaces to APIs or ports

✅ Compatible with planner-based orchestration ✅ Stateful example actor support for AI assistants, semantic memory, long-lived processes

✅ Summary¶

Provides virtual actor patterns for distributed, isolated, persistent logic
Supports Orleans, Dapr, or Akka, selected at generation time
Fully integrates with OpenTelemetry, semantic AI, and event-driven systems
Can power workflow engines, chat states, job controllers, and more

⏱️ Scheduler and Background Job Models¶

The SchedulerModel provides support for background processing and scheduled jobs, enabling microservices to execute logic outside of direct request/response flows.

Use cases include:

Periodic cleanups or batch tasks
Time-based triggers (e.g., reminder notifications)
Long-running workflows
Asynchronous job queues

🧩 Supported Scheduling Frameworks¶

Scheduler	Project	Description
Hangfire	`SchedulerModel.Hangfire`	Background jobs with retry, dashboards, CRON
Quartz.NET	`SchedulerModel.Quartz`	Enterprise-grade job scheduler
Azure Functions	`ServiceModel.AzureFunction`	Timer-based execution in serverless context

The template generates the correct scheduling model depending on --SchedulerModelType or --ServiceModelType.

⚙️ Template Parameters¶

Parameter	Description
`--SchedulerModelType`	`Hangfire`, `Quartz`, or `None`
`--ServiceModelType`	If set to `AzureFunction`, includes timer triggers
`--UseOpenAI` / `--UseSemanticKernel`	Jobs can call AI skills
`--UseFeatureFlags`	Jobs can be conditionally registered

🔧 Hangfire Integration¶

📂 Structure¶

SchedulerModel.Hangfire/
  ├── Jobs/
  │   └── CleanupJob.cs
  ├── Configuration/
  └── Extensions/

Feature	Description
CRON support	Declarative or programmatic
Retry and retry delay	Out-of-the-box
Dashboard	`/hangfire` secured endpoint
Storage	SQL Server, Redis, or in-memory options
Distributed lock support	Built-in for cluster-safe execution

✅ Registered via UseHangfire() and AddHangfireJobs()

🔧 Quartz.NET Integration¶

📂 Structure¶

SchedulerModel.Quartz/
  ├── Jobs/
  │   └── GenerateInvoicesJob.cs
  └── QuartzConfiguration/

Feature	Description
CRON or Interval triggers	Declarative or fluent API
Durable job definitions	Persistence in DB (optional)
Clustering support	Quartz.NET built-in
Middleware hooks	Add retry, tracing, correlation ID

✅ Jobs registered at startup via QuartzExtensions.RegisterJobs() ✅ Hosted as part of the main worker process or external worker

🌩️ Azure Function Timer Triggers¶

📂 Structure¶

ServiceModel.AzureFunction/
  └── TimerTriggers/
      └── SendDigestEmailsFunction.cs

Feature	Description
CRON expressions	`"0 /30 * * *"` format
Native Azure scaling	Based on trigger volume
AppSettings based	Bindings from `host.json` and environment
Durable Tasks	Optional extension for workflows

✅ Works in both isolated and full-function runtime

🧪 Example: Registering a Hangfire Job¶

public class SendEmailRemindersJob : IBackgroundJob
{
    public async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        // logic to send reminders
    }
}

RecurringJob.AddOrUpdate<SendEmailRemindersJob>(
    job => job.ExecuteAsync(CancellationToken.None),
    Cron.Hourly);

🧪 Testing Background Jobs¶

Scenario	Tooling
Job logic unit test	xUnit or MSTest
Schedule/CRON test	CronUtils or test clock
Hangfire dashboard test	Selenium or headless browser
Mock time for timers	TestServer + `DateTimeProvider` override

🧠 AI Integration with Jobs¶

Jobs can invoke Semantic Kernel skills or trigger AI workflows
Example: DailySummaryJob → calls SummarizeDomainActivitySkill
AI-based planners can register jobs dynamically (future roadmap)

✅ Ideal for automating reports, insights, event summaries, feedback loops

🔒 Security & Observability¶

Hangfire and Quartz jobs:
- Use ILogger<> for tracing
- Include correlation ID + tenant context
- Optional OpenTelemetry spans
Hangfire dashboard:
- Protected via JWT / policy-based guards

✅ Summary¶

Supports robust background job execution with:
- Retry logic
- Metrics
- CRON scheduling
- AI integration
- Enables serverless, clustered, or hosted models
- Cleanly integrated into the Clean Architecture flow

🤖 Semantic Kernel and AI Extensions¶

The SemanticKernel integration layer empowers microservices with AI orchestration capabilities, enabling them to:

Invoke LLM-backed skills and workflows
Respond to natural language prompts
Execute AI-enhanced tasks in background jobs, APIs, or actors
Collaborate with other services using planner-generated flows

🧠 This is the foundation for ConnectSoft AI Agents, intelligent assistants, and autonomous feature delivery.

🧩 Core Project¶

AI/
└── SemanticKernel/
    ├── Skills/
    ├── Plugins/
    ├── Configuration/
    └── KernelHost.cs

✅ Generated when --UseSemanticKernel true or an agent explicitly activates this feature.

⚙️ Template Parameters¶

Parameter	Description
`--UseSemanticKernel`	Enables SK kernel host, plugin infrastructure
`--UseOpenAI`	Adds connectors for OpenAI, Azure OpenAI
`--UseMicrosoftBotBuilder`	Enables conversation flow using SK-based responses
`--ActorModelType`	Can link SK flows to actors
`--ServiceModelType`	Allows SK triggers from APIs or gRPC

🧠 Skills and Plugins Structure¶

Folder	Purpose
`Skills/`	C#-based native skills for AI workflows
`Plugins/`	Prompt-template based skills (functions)
`KernelHost.cs`	Central entry point to configure kernel, memory, and planners

Example: Native Skill¶

public class CreateInvoiceSkill
{
    [KernelFunction]
    public Task<string> GenerateInvoiceAsync(string customerId)
    {
        // domain call here
        return Task.FromResult("Invoice created for " + customerId);
    }
}

Example: Prompt Plugin¶

Plugins/CustomerSupport/
└── SummarizeTicket/
    ├── config.json
    └── skprompt.txt

🔌 LLM Connectors¶

Out-of-the-box support for:

✅ OpenAI (ChatGPT, GPT-4)
✅ Azure OpenAI
✅ Ollama (local models)
✅ HuggingFace
✅ PromptFlow (plugin-based)
✅ RAG: Retrieval-Augmented Generation (via memory store)

🧠 Kernel Features Enabled¶

Capability	Description
Planner Support	Sequential, Stepwise, or Function-based plans
Memory Support	In-memory or external stores (e.g., Redis, CosmosDB)
Context Propagation	Correlation ID, tenant ID, execution ID
Streaming Responses	For chat, SignalR, or BotFramework
Logging and Observability	Via OpenTelemetry spans, semantic traces

📡 Integration Points¶

Runtime	How SK is Used
REST API	Expose AI prompt endpoints or chat endpoints
gRPC / GraphQL	Create AI-enhanced services
Background Job	Automate scheduled AI summaries, insights, decisions
Actor	Attach skills to a single grain or actor type
Bot Framework	Use skills as part of adaptive dialog responses
Message Consumers	Trigger AI from events and route output via command bus

🧪 Testing & Tooling¶

Tool	Use
KernelTestHost	Mock LLMs in unit tests
Prompt Engineering	Use `config.json` and `promptflow.json` for structure
AIOutputRecorder	Capture output of skills in event log / observability layer

✅ Semantic test harness included ✅ Optional skill metrics (sk_invocations_total, etc.)

📖 Example Use Cases¶

GenerateCustomerSummarySkill → called via gRPC or background job
ValidateInsuranceClaimSkill → runs inside a grain
RouteSupportTicketSkill → triggered via SignalR
OnboardingPlanner → multi-step process planner
TranslateLanguageSkill → exposed via API and Bot

🧠 Agent-Aware Structure¶

All skills are discoverable by agents via directory structure and metadata
AI agents can:
- Register new skills
- Rewire flows dynamically
- Auto-generate plugin prompts from domain events

✅ Fully composable into end-to-end autonomous execution chains

✅ Summary¶

The template includes first-class AI orchestration support
Built on Semantic Kernel, with connectors, skills, memory, and plugins
Ready for use in APIs, bots, actors, events, and planners
Enables agentic orchestration across microservices and AI workflows

💬 Microsoft Bot Framework Integration¶

The BotModel layer enables microservices to act as conversational agents, integrating with the Microsoft Bot Framework to deliver:

Interactive chat experiences
Adaptive dialogs
OAuth-based identity flows
AI-enhanced skills and prompts
Voice or omnichannel connectivity (Teams, Telegram, Web)

This allows microservices to expose business logic conversationally, powered by both domain use cases and Semantic Kernel skills.

📦 Core Project¶

Bot/
└── BotModel/
    ├── Dialogs/
    ├── Cards/
    ├── Controllers/
    ├── Configuration/
    └── Middleware/

✅ This is generated if --UseMicrosoftBotBuilder true.

⚙️ Template Parameters¶

Parameter	Description
`--UseMicrosoftBotBuilder`	Enables bot model scaffolding
`--UseSemanticKernel`	Connects bot dialogs to SK skills
`--UseOpenAI`	Enables natural language fallback or enrichment
`--ServiceModelType`	`RestApi` must be included to expose `/api/messages`
`--UseAuthentication`	Configures OAuth2 flows with Bot Framework
`--ActorModelType`	Optional: link Bot sessions to actor state

🔌 Key Features Included¶

Feature	Description
Adaptive Dialogs	Supports conditional and multi-step dialogs
OAuth Support	Integrated with Azure AD or custom identity provider
Conversation State	Memory and transcript support
Channel Support	Web Chat, MS Teams, Telegram, Facebook, WhatsApp
Error Handling	Global exception handler and fallback replies
Adaptive Cards	Custom card rendering with rich data from the domain layer
AI Orchestration	Integration with SK planners or OpenAI completions

🔄 Bot Runtime Flow¶

sequenceDiagram
    User->>BotController: POST /api/messages
    BotController->>Adapter: Process activity
    Adapter->>Dialog: Start or continue dialog
    Dialog->>UseCaseHandler: Call domain logic
    Dialog->>SemanticKernel: Call SK skill (optional)
    Dialog->>User: Send adaptive card or text response

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

🧠 Adaptive Dialog Example¶

public class OnboardingDialog : ComponentDialog
{
    public OnboardingDialog(...) : base(nameof(OnboardingDialog))
    {
        var steps = new WaterfallStep[]
        {
            AskNameAsync,
            ConfirmAsync,
            CompleteAsync
        };

        AddDialog(new WaterfallDialog(nameof(WaterfallDialog), steps));
    }
}

✅ Each dialog step may call:

Domain use case
Actor method
AI skill
Background job
Message dispatch

📝 Adaptive Card Support¶

{
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    { "type": "TextBlock", "text": "Welcome!" }
  ],
  "actions": [
    { "type": "Action.Submit", "title": "Continue", "data": { "action": "next" } }
  ]
}

Cards live under BotModel/Cards/
Connected to dialog state and tenant context
Themeable and data-driven

Supports:
- Azure AD
- External identity (e.g., WordPress, Firebase)
- Uses OAuthPrompt + SignInCard flow
- Captures token in user state and passes it into service layer

✅ Required for premium access, personalization, or external APIs

🧠 Integration with AI & Skills¶

Each bot dialog can invoke Semantic Kernel skills directly
Conversations may use:
- LLM completions (ChatGPT, Azure OpenAI)
- Summarization, planning, transformation
- RAG: memory + semantic context

✅ Response = domain → AI skill → card/message

🔄 Connect with Actors¶

If --ActorModelType is enabled, each conversation can:

Be mapped to a grain (e.g., IUserSessionGrain)
Maintain state across multiple dialogs
Store history, preferences, or progress

🧪 Testing Support¶

Test Type	Tools
Dialog tests	xUnit + Bot Framework test client
Message endpoint	Integration test with `/api/messages`
Card rendering	Schema validation and JSON schema testing
OAuth flow	Bot Emulator + test IDP

🧠 Agent Integration¶

Agents can auto-generate dialogs from:
- Domain use cases
- Event blueprints
- AI plugins
Dialogs are tagged with metadata to support:
- Planner orchestration
- Intent recognition
- Skill registration

✅ Enables full conversational integration of business workflows

✅ Summary¶

Provides a full-featured Bot Framework interface
Enables conversational flows over business logic
Integrates seamlessly with:
- OAuth
- Semantic Kernel
- Actors
- Use cases
- Messaging
- Delivers enterprise-ready conversational UX for AI and SaaS systems

🧩 Cross-Cutting Concerns and Middleware Pipeline¶

Cross-cutting concerns (CCCs) are non-functional capabilities that apply across the microservice — regardless of domain logic, transport model, or database engine.

The ConnectSoft Microservice Template includes built-in, opt-in, and composable support for the most important cross-cutting concerns, ensuring:

🧱 Consistency
🔍 Observability
🔐 Security
🛠 Maintainability
📊 Extensibility

🔧 Automatically Included Middleware¶

The template registers all CCCs inside a unified, composable extension chain:

builder.Services.AddMicroserviceServices(configuration);
app.UseMicroservicePipeline();

These extension methods are located in:

Application/
└── MicroserviceServiceCollectionExtensions.cs
└── MicroserviceApplicationBuilderExtensions.cs

✅ Included Cross-Cutting Concerns¶

Concern	Description
Authentication & Authorization	JWT bearer, scopes, tenant-based policies
Correlation ID	Request ID propagation (via header or trace context)
Tenant Context	Header/claim-based multi-tenant resolver
Exception Handling	Centralized exception mapping using RFC 7807 (ProblemDetails)
Validation	FluentValidation (auto-wired for request models)
Swagger UI	Only in development or if `--Swagger true`
API Versioning	Via route segment or header
CORS	Configurable origin and methods
Rate Limiting	Optional integration (YARP/gateway or custom)
Feature Flags	`Microsoft.FeatureManagement` toggles
Logging	Serilog with OpenTelemetry enrichment
Tracing & Metrics	OpenTelemetry span/metric auto-registration
Health Checks	Liveness/readiness/startup + custom probes

🧱 Middleware Ordering¶

HTTP Request Pipeline:
  → CorrelationIdMiddleware
  → ExceptionHandlingMiddleware
  → TenantResolutionMiddleware
  → AuthenticationMiddleware
  → AuthorizationMiddleware
  → RequestLoggingMiddleware
  → EndpointRoutingMiddleware
  → Swagger/Docs
  → Health Check Middleware

✅ You can override this order in Program.cs, or selectively disable middleware in tests.

🔁 Conditional Activation¶

Flag	Effect
`--Swagger`	Enables Swagger generator and UI
`--HealthCheck`	Enables `/health/live`, `/health/ready`, etc.
`--FeatureFlags`	Enables feature toggle system
`--OpenTelemetry`	Injects OTLP metrics, spans, log enrichers
`--CORS`	Enables origin filtering
`--Logging`	Switches between `Serilog`, `Log4Net`, or `None`

🧪 Exception Handling Example¶

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation Failed",
  "status": 400,
  "traceId": "00-1e0e-...-00",
  "errors": {
    "CustomerId": ["CustomerId is required."]
  }
}

Returned by default via ProblemDetails middleware.

🔒 Tenant Guard Filters¶

Multi-tenant awareness flows through:

HTTP headers (X-Tenant-Id)
JWT claims (tenantId)
Event headers (MassTransit, NServiceBus)
Actor grains and bot dialogs (via context injection)

✅ TenantContext is available via DI anywhere in the app.

🧠 Observability Chain¶

All requests and use cases are automatically:

🧭 Enriched with trace ID and tenant ID
📡 Exposed as OpenTelemetry spans
📊 Measured with Prometheus-style counters:
request_duration_seconds
use_case_errors_total
message_processed_total

🧪 Testing CCCs¶

Concern	Test Strategy
Exception handling	WebApplicationFactory + assertions
Correlation ID	Header injection + response echo
Validation	FluentValidation test runner
Swagger	JSON schema validator
Health checks	`/health/ready` ping with mock service check
Tenant enforcement	Role/claim filters under different user tokens

🧠 Agent Awareness¶

All CCCs are annotated in metadata for AI orchestration
ConnectSoft agents:
- Inspect Program.cs and MicroservicePipeline
- Override or extend CCCs via skill hooks (e.g., AddRetryOnUseCaseFailure())

✅ Summary¶

The ConnectSoft Microservice Template includes a robust, modular middleware pipeline that supports:

✅ Security, observability, and developer experience
✅ Multi-tenant and multi-environment compatibility
✅ Agentic overrides and runtime flexibility
✅ Automation-ready tracing, logging, and error contracts

📊 OpenTelemetry, Metrics, and Distributed Tracing¶

Observability is a first-class concern in the ConnectSoft Microservice Template.

By integrating OpenTelemetry, the template provides structured tracing, logging, and metrics across all execution flows — whether initiated by:

REST/gRPC/SignalR APIs
Event consumers or message buses
Background jobs, actors, bots, or AI skills

📈 All telemetry is zero-config by default, but extensible and pluggable.

⚙️ Template Parameters¶

Parameter	Description
`--OpenTelemetry`	Enables automatic registration of tracing and metrics
`--Logging`	Enables enriched structured logging (Serilog, Log4Net)
`--UseApplicationInsights`	Connects to Azure Monitor AppInsights (optional)
`--ResourceMonitoring`	Adds CPU, memory, thread pool metrics (experimental)

🔧 OpenTelemetry Components Registered¶

Area	What’s Wired
Tracing	Distributed spans, context propagation (W3C)
Metrics	Custom counters, histograms, gauges
Logging	Structured logs enriched with trace and tenant context
Exporters	OTLP, Prometheus, Jaeger, Zipkin, App Insights
Context	CorrelationId, TenantId, TraceId auto-enriched
Semantic Conventions	Predefined span names for use cases, events, actors, APIs

📌 Tracing: Span Lifecycle¶

Every request through the microservice results in one or more OpenTelemetry spans, automatically generated and labeled.

Incoming Request → API Span
                → UseCase Span
                → DB Span (e.g., NHibernate)
                → Messaging Span (if bus used)

Example: REST API call trace¶

GET /orders/123
├── span: HTTP GET /orders/{id}
│   ├── span: Execute GetOrderDetailsUseCase
│   └── span: NHibernate SQL SELECT ...

✅ Traces are auto-linked with traceparent headers and persisted by exporters.

🧮 Metrics: Prometheus-Compatible¶

Default Metrics Included¶

Metric	Description
`request_duration_seconds`	Histogram of request execution time
`use_case_execution_total`	Counter of use case runs
`event_processing_duration_seconds`	Message bus consumer latency
`active_grains_count`	(Orleans/Dapr) current actor load
`background_job_success_total`	Hangfire/Quartz job success count

📍 Exposed at /metrics and scraped by Prometheus.

Custom Metrics with Instrumentation API¶

private static readonly Histogram<double> OrderValueHistogram =
    MyMeter.CreateHistogram<double>("order_value_distribution");

OrderValueHistogram.Record(order.TotalValue);

✅ All metrics are enriched with:

tenant_id
trace_id
use_case
host_environment

🧠 Context Enrichment¶

All telemetry includes:

X-Correlation-ID
X-Tenant-ID
X-Trace-ID (from W3C TraceContext)

➡ Automatically propagated through:

HTTP headers
gRPC metadata
Event headers
SignalR context
Actor and job execution

🔭 Exporter Support¶

Exporter	Status
Prometheus	✅ Default
Jaeger	✅ Via environment/launch config
Zipkin	✅ Optional
Azure App Insights	✅ via `--UseApplicationInsights`
OTLP HTTP / gRPC	✅ Supported for all backend platforms

🧪 Testing and Validation¶

Tool	Use
OpenTelemetry Collector	Forward traces to backends
Prometheus UI	Scrape and monitor metrics
Jaeger UI	Trace visualization
Serilog TestSink	Capture structured logs in tests
`ActivitySourceListener`	Intercept spans in test harness

🧠 Agent Awareness¶

Spans and metrics are tagged to support:
- Use case performance analysis
- AI skill bottleneck detection
- Workflow heatmaps
- ConnectSoft AI agents can:
- Attach additional tags at runtime
- Generate observability dashboards
- Trigger alerts or summaries using SK

✅ Semantic Kernel planners may use metrics to optimize execution order

✅ Summary¶

The template enables full-stack observability via OpenTelemetry
Traces, logs, and metrics are structured, tagged, and exportable
Works seamlessly with REST, gRPC, eventing, jobs, actors, and AI
Supports developer productivity, AI debugging, and enterprise monitoring

🔐 Configuration and Secrets Management¶

The template provides a secure, modular, and environment-aware configuration system, using:

🔁 .NET's IOptions<T> pattern
🔐 Integration with Azure Key Vault and Azure App Configuration
📦 Multi-environment config layering
✅ Validation and defaults
🧠 AI agent compatibility for dynamic reconfiguration

⚙️ Configuration is centrally declared, strongly typed, and automatically validated on startup.

📦 Core Project¶

Common/
└── MyService.Options/
    ├── JwtOptions.cs
    ├── ServiceBusOptions.cs
    ├── SemanticKernelOptions.cs
    ├── MongoDbOptions.cs
    ├── NhibernateOptions.cs
    └── ...

🧩 Supported Configuration Providers¶

Source	Purpose
`appsettings.{Environment}.json`	Local, per-environment config
`Azure App Configuration`	Centralized key-value store (optional)
`User Secrets`	Dev-only secret management
`Azure Key Vault`	Secure, externalized secrets
`Environment Variables`	Container/K8s overrides
`Command Line Args`	Runtime config during launch

⚙️ Template Parameters¶

Parameter	Description
`--AdditionalConfigurationProvider`	`AzureAppConfiguration`, `None`
`--UseAuthentication`	Adds `JwtOptions`
`--MessagingModelType`	Adds bus-specific options (e.g., RabbitMQ, ServiceBus)
`--PersistenceModelType`	Adds SQL/Mongo connection options
`--UseOpenAI`	Adds OpenAI and Semantic Kernel options
`--UsePulumi`	Enables dynamic secrets from provisioned vault

🧱 IOptions Pattern with Validation¶

Each config section is bound to a typed POCO, registered with validation.

builder.Services
    .AddOptions<JwtOptions>()
    .Bind(configuration.GetSection("Jwt"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

Example: JwtOptions.cs¶

public class JwtOptions
{
    [Required]
    public string Authority { get; set; }

    [Required]
    public string Audience { get; set; }
}

🔄 Environment Config Layering¶

appsettings.json
↳ appsettings.Development.json
↳ appsettings.Production.json
↳ Environment Variables
↳ secrets.json (dev only)
↳ Azure App Config (optional)
↳ Key Vault (optional)

✅ Hierarchical override support
✅ Safe for containerized deployments
✅ Secrets never embedded in source code

🔐 Azure Key Vault Integration¶

If enabled:

Automatically resolves AzureKeyVault__Endpoint from environment
Injects secrets into configuration provider
Supports:
- Connection strings
- API keys
- Tokens, passwords
- OpenAI credentials

az keyvault secret set --vault-name my-vault --name Jwt--Authority --value https://login.example.com

✅ Keys match config binding (e.g., Jwt:Authority)

🔑 Azure App Configuration Integration¶

If --AdditionalConfigurationProvider AzureAppConfiguration:

Load all shared/global configs from App Config
Key filtering supported (Microservices:MyService:*)
Feature flags are synced from the same source

✅ Easily update config across 100s of services

🧪 Validation and Fail-Fast Behavior¶

All IOptions<T> are validated at startup.

If required field is missing or malformed:

❌ App fails to start
🔎 Error includes section name + failed validation reason
✅ Ideal for CI/CD pipeline enforcement

🧠 Agent Use Cases¶

Agents can:

Generate .json or .yml configuration blocks
Inject secrets via az or Terraform commands
Toggle features dynamically via App Config
Securely request and rotate credentials from Key Vault

✅ Semantic Kernel planners may react to config changes or feature toggles

🧪 Testing Strategy¶

Method	Use
Unit tests for IOptions	Validate config model binding
Secrets mocking	Inject memory configuration source
AppSettings overrides	Test per-environment behavior
AppConfig & Vault simulation	Use Azure SDK test helpers

✅ Summary¶

Config is modular, strongly typed, and secure
Fully supports:
- Azure AppConfig
- Azure Key Vault
- IOptions pattern
- Compatible with:
- CI/CD
- Kubernetes
- Agentic and AI-driven systems

🧿 Feature Flags and Edition-Aware Behavior¶

The ConnectSoft Microservice Template supports dynamic feature toggling and edition-specific behavior using:

✅ Microsoft.FeatureManagement (built-in to .NET)
✅ Azure App Configuration integration
✅ Tenant- and edition-aware evaluation
✅ Declarative or code-based flag checks
✅ AI agent compatibility for enabling/disabling features at runtime

🎛 Feature flags allow services to conditionally activate functionality based on tenant, edition, stage, or experiment.

📦 Core Project Involved¶

Common/
└── MyService.Options/
    └── FeatureManagement/
        └── FeatureFlagExtensions.cs

⚙️ Template Parameters¶

Parameter	Description
`--FeatureFlags`	Enables feature management subsystem
`--FeatureFlagsProvider`	`AppSettings`, `AzureAppConfiguration`
`--UsePulumi`	Can provision initial flags in App Config
`--UseSemanticKernel`	Allows planner-based feature activation
`--UseMicrosoftBotBuilder`	Dialog steps can be gated by flags

🧭 Feature Flags Model¶

Level	Description
Global	Affects all tenants/services
Tenant-Scoped	Applies only to a tenant (`X-Tenant-ID`)
Edition-Scoped	Tied to SaaS edition metadata (e.g., Free, Pro, Enterprise)
Stage-Based	Dev/Test/Staging/Production rollout

Flags are defined as:

{
  "FeatureManagement": {
    "EnableChatbot": true,
    "EnableAuditTrail": false,
    "EnableSKPlanning": {
      "EnabledFor": [
        {
          "Name": "Tenant",
          "Parameters": { "TenantId": "tenant-xyz" }
        }
      ]
    }
  }
}

🧩 Sample Usage in Code¶

Conditional service registration:¶

services.AddFeatureFlagConditional<INotificationService, DefaultNotificationService>(
    feature: "EnableNotifications");

Use case filter:¶

if (!await _featureManager.IsEnabledAsync("EnableAuditTrail"))
    return;

Razor page or controller condition:¶

@if (await featureManager.IsEnabledAsync("EnableSemanticSkills"))
{
    <button>Use AI Assistant</button>
}

🛂 Edition-Aware Behavior¶

Using EditionMetadata, a microservice can:

Check if a tenant is on a specific edition (e.g., Pro)
Gate features like:
- Semantic search
- API rate limits
- Advanced insights
- Real-time AI planner usage

if (_edition.Is("Enterprise") && await _feature.IsEnabledAsync("EnableRealtimeAI"))
{
    // Allow premium AI skill
}

✅ EditionMetadata injected via header, token, or feature store
✅ Can also be used in SK planner prompts

☁️ Azure App Configuration Support¶

If --FeatureFlagsProvider AzureAppConfiguration:

Flags are synced in real-time
No need to restart service to apply flag changes
Supports:
- Targeting filters
- Rollout strategies
- Key prefixing (MyService:*)

App Configuration Key: MyService:FeatureManagement:EnableBetaUI = true

✅ Managed via Azure Portal or CI/CD tools (Pulumi, Terraform, az CLI)

🧪 Testing and Debugging¶

Method	Tool
Feature toggle logic	Unit test with in-memory feature provider
Edition rules	Use mock tenant and edition metadata
AppConfig integration	Use `AzureAppConfigurationEmulator` or local KV
Planner behavior	Test planner prompt reactions to disabled skills

🧠 AI and Agent Usage¶

Agents can:

Discover active/inactive features dynamically
Enable experimental features during planning
Annotate SK prompts with active feature list
Roll out features to specific tenants/editions

✅ Fully compatible with planner-based decisions ✅ Can be embedded in Bot dialogs, dashboards, skills

✅ Summary¶

Feature toggling is declarative, scoped, and traceable
Supports tenant, edition, stage, and runtime toggles
Aligned with Azure App Config, Semantic Kernel, and agentic workflows
Drives experimentation, gradual rollout, and user-tiered functionality

❤️‍🩹 Health Checks and Readiness Probes¶

Health checks ensure that services are:

Alive (running)
Ready (able to serve traffic)
Started (fully initialized)

The ConnectSoft Microservice Template includes built-in support for all three types of checks, fully aligned with:

🔄 Kubernetes probes
☁️ Azure App Service health ping
🧪 Dev/Test monitoring
🔎 Observability systems (Prometheus, Application Insights)

📦 Core Support¶

If --HealthCheck is enabled, the template auto-registers:

Endpoint	Purpose	Path
Liveness	Is the process alive?	`/health/live`
Readiness	Is the service ready to receive traffic?	`/health/ready`
Startup	Has it finished initialization?	`/health/startup`

🛡️ Endpoints are grouped under the built-in HealthChecks subsystem from ASP.NET Core.

⚙️ Template Parameters¶

Parameter	Description
`--HealthCheck`	Enables core `/health/*` endpoints
`--HealthCheckUI`	Adds optional dashboard (e.g., `/health-ui`)
`--UsePulumi`	Deploys AppService with built-in ping config
`--ServiceModelType`	Registers HTTP middleware in REST, gRPC, or Function host

🩺 Health Check Configuration¶

In Program.cs:

builder.Services.AddHealthChecks()
    .AddSqlServer(...)
    .AddMongoDb(...)
    .AddRedis(...)
    .AddMassTransit(...)
    .AddCheck<MyServiceCheck>("my_service_logic");

app.UseHealthChecks("/health/live", new HealthCheckOptions { Predicate = _ => false });
app.UseHealthChecks("/health/ready", new HealthCheckOptions { Predicate = hc => hc.Tags.Contains("ready") });

🧩 Tagged Health Checks¶

Each check is tagged for granular behavior:

Tag	Description
`live`	Process health (e.g., is Kestrel running?)
`ready`	Readiness (e.g., DB connection, bus connectivity)
`startup`	Cold start logic (e.g., migrations complete)

✅ Allows individual endpoints to only include specific checks

🧪 Examples¶

services.AddHealthChecks()
    .AddMongoDb(connectionString, name: "Mongo", tags: new[] { "ready" })
    .AddCheck<MemoryUsageHealthCheck>("Memory", tags: new[] { "live" });

🔬 Custom Health Check Example¶

public class SemanticKernelHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken token)
    {
        return Task.FromResult(HealthCheckResult.Healthy("SK initialized"));
    }
}

✅ Register with .AddCheck<SemanticKernelHealthCheck>("SemanticKernel", tags: new[] { "ready" })

🌍 Kubernetes Probes Example¶

livenessProbe:
  httpGet:
    path: /health/live
    port: 80
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health/ready
    port: 80
  initialDelaySeconds: 10
  periodSeconds: 5

🖥️ Health Check UI (Optional)¶

If --HealthCheckUI:

Hosted at /health-ui
Shows:
- Last status
- Duration
- Failures
- Supports multiple services (aggregate dashboard)

📊 Metrics and Observability¶

Each check:

Adds span to OpenTelemetry trace
Contributes to /metrics for Prometheus:
- health_check_duration_seconds
- health_check_failures_total

✅ Easily correlated with logs and alerts

🧠 AI & Agent Usage¶

Agents may:

Inject checks for:
- AI skill registry health
- Plugin API availability
- Memory or token quota
- Monitor readiness before deploying dependent systems
- Use AI-driven planners to react to service health (e.g., retry, reroute, notify)

✅ Skills and grains can expose custom check interfaces ✅ Future support: planner-based self-healing logic

✅ Summary¶

The template includes modular, observable, and probe-ready health checks
Supports:
- Live/readiness/startup probes
- Custom application logic
- Third-party dependencies
- Aligns with:
- Kubernetes
- Azure App Service
- DevOps alerts
- AI agent workflows

🔐 Authentication, Authorization, and Multi-Tenancy¶

The ConnectSoft Microservice Template provides a secure and multi-tenant-ready architecture by integrating:

🔐 OAuth2 / OpenID Connect authentication
🛡 Role- and scope-based authorization
🌍 Tenant-aware filtering and routing
🧱 Middleware and attribute-based access control
🧠 Compatibility with AI agent claims and tenant metadata

This ensures that every microservice is secure by default, yet extensible for complex SaaS needs.

⚙️ Template Parameters¶

Parameter	Description
`--UseAuthentication`	Enables JWT bearer support
`--UseMicrosoftBotBuilder`	Enables identity support in bot conversations
`--ServiceModelType`	Required for REST/gRPC/SignalR auth integration
`--UsePulumi`	Auto-provisions Azure App registrations and permissions
`--UseFeatureFlags`	Can conditionally enable/disable per-tenant features

🔐 Authentication (JWT + OAuth2)¶

Built-in Integration With:¶

✅ OpenIddict (default identity server)
✅ Azure Active Directory
✅ Custom OIDC providers (e.g., Auth0, IdentityServer4)

Key Middleware:¶

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = config["Jwt:Authority"];
        options.Audience = config["Jwt:Audience"];
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true
        };
    });

📦 Bound to strongly-typed JwtOptions via IOptions<T>

🛡 Authorization¶

Authorization can be enforced via:

Technique	Usage
`[Authorize(Roles = "Admin")]`	Attribute-based
`services.AddAuthorization(options => { ... })`	Policy-based
`.RequireScope("orders.read")`	Scope validation
`IAuthorizationHandler`	Custom logic (e.g., per-tenant permissions)

✅ Supports nested policies (e.g., "RequireAdminForTenant")

🌍 Multi-Tenancy Support¶

Each request is evaluated with a TenantContext, populated via:

🔹 X-Tenant-ID header
🔹 tenantId JWT claim
🔹 Bot dialog or actor context
🔹 Azure App Config for edition overrides

Middleware Auto-Registers:¶

app.UseTenantResolution();

✅ Injected globally via ITenantContextAccessor ✅ Tenant ID is tagged in:

Logs
Traces
Events
Metrics
AI prompts

🧱 Role & Scope Mapping Example¶

{
  "sub": "user-123",
  "tenantId": "tenant-abc",
  "roles": ["Manager"],
  "scp": ["orders.read", "invoices.create"]
}

Mapped internally to:

ClaimsPrincipal roles
Policy handlers
Multi-tenant guards (e.g., restrict data access to user's tenant)

🧪 Testing Auth¶

Scenario	Strategy
REST API with token	Use mocked JWT via test token issuer
Tenant isolation	Use alternate tenant ID claims or headers
Scope enforcement	Add/remove `scp` claim and test policies
Bot auth	Use Bot Emulator with OAuth flow
Actor + auth	Test grain calls with tenant-mocked context

🧠 Agent and AI Integration¶

Agents can:
- Create new OAuth clients in Pulumi
- Assign user roles and scopes
- Validate identity during Bot onboarding
- Store tenant metadata in Semantic Kernel memory
- SK skills can:
- Require auth
- Route data based on tenant
- Auto-adjust prompts per edition level

✅ Permissions are part of execution context in AI workflows ✅ Identity is compatible with planner decisions and feature gates

📌 Security Hardening Best Practices (Included)¶

✅ HTTPS enforced via Kestrel or NGINX config
✅ Rate limiting and IP filter stubs available
✅ Token lifetime validation
✅ CORS restricted per environment
✅ Token propagation across message bus and job context

✅ Summary¶

Built-in authentication and authorization
Multi-tenant and edition-aware logic
Compatible with:
- REST/gRPC/Bot/SignalR
- Events, actors, and AI
- Secure defaults, extensibility points, and CI/CD support
- Ideal for SaaS, enterprise, and federated scenarios

🔄 Background Jobs and Retry Mechanics¶

The ConnectSoft Microservice Template includes modular support for background job execution, enabling microservices to:

Run asynchronous and delayed tasks
Process long-running or scheduled jobs
Ensure reliability through retries, timeouts, and fallbacks
Scale job processing across distributed nodes
Integrate with Hangfire, Quartz, Azure Functions, and Polly

⚙️ Designed for resilience, observability, and composability, job execution is wired through clearly separated scheduler models.

📦 Job Execution Models¶

Scheduler	Project	Description
Hangfire	`SchedulerModel.Hangfire`	Background job runner with dashboard, CRON, and retries
Quartz.NET	`SchedulerModel.Quartz`	Durable job scheduling, clustering support
Azure Functions	`ServiceModel.AzureFunction`	Timer-based serverless jobs (if selected)

⚙️ Template Parameters¶

Parameter	Description
`--SchedulerModelType`	`Hangfire`, `Quartz`, or `None`
`--UseOpenAI` / `--UseSemanticKernel`	Allows jobs to trigger AI skills
`--UsePulumi`	Deploys job runtime containers or schedules
`--MessagingModelType`	Enables background command queues or worker subscribers
`--UseHangfireDashboard`	Exposes dashboard at `/hangfire` (auth required)

🧠 Job Class Structure (Hangfire Example)¶

public class ProcessInvoiceJob : IBackgroundJob
{
    public async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        // Call use case, actor, or message bus
    }
}

Registered in HangfireJobRegistry.cs:

RecurringJob.AddOrUpdate<ProcessInvoiceJob>(
    job => job.ExecuteAsync(CancellationToken.None),
    Cron.Daily);

✅ Fluent or CRON syntax ✅ Retry and exponential backoff supported automatically

🔁 Retry and Fallback Patterns¶

The template uses Polly internally to provide:

Pattern	Description
`Retry`	Retry on failure N times
`CircuitBreaker`	Open circuit after N failures
`Timeout`	Cancel long-running execution
`Fallback`	Recover gracefully when all else fails

Example¶

var policy = Policy
    .Handle<TransientException>()
    .RetryAsync(3);

await policy.ExecuteAsync(() => handler.ExecuteAsync(request));

✅ Polly is included for:

Job handlers
Message consumers
Use case orchestrators

📊 Observability in Jobs¶

✅ All jobs are traced via OpenTelemetry spans
✅ Metrics exposed:
- background_job_duration_seconds
- job_failures_total
- job_queue_depth
- ✅ Job name, tenant ID, and correlation ID auto-tagged

🧪 Testing Background Logic¶

Concern	Strategy
Job logic	Test with DI-injected mocks and unit tests
Retry	Simulate transient failures
Hangfire	Use in-memory storage, assert scheduling
Quartz	Assert trigger state and misfire recovery

✅ Retry logic tested with injected FakePolicy ✅ Time manipulation via SystemClock.Override

🧠 AI Job Use Cases¶

Schedule daily summary reports from AI
Run SK-powered semantic workflows every X hours
Retry knowledge ingestion on failure
Periodically refresh embeddings or documents
Auto-invoke BotFramework proactive messages

✅ AI skills used as job entrypoints or steps ✅ Skills can trigger commands, log insight, or dispatch messages

🧭 Integration Points¶

✅ Can dispatch domain events
✅ Can execute use case handlers
✅ Can call APIs or publish messages
✅ Can be triggered via webhooks, events, or schedules

🔒 Security and Isolation¶

Jobs execute under:
- Assigned TenantId (injected into context)
- Scoped lifetime and execution ID
- Dashboard access (Hangfire): protected via [Authorize]
- Failures: auto-logged, retried, and pushed to dead-letter storage (if bus enabled)

✅ Summary¶

Fully supports resilient background processing
Retry, fallback, and timeouts via Polly
Composable with:
- Message bus
- Domain model
- AI skills
- Observable, secure, and multi-tenant aware
- Scheduler pluggable: Hangfire, Quartz, Azure Functions

🐳 Docker, Compose, and Containerization¶

The ConnectSoft Microservice Template is designed with cloud-native, container-first principles, enabling:

Local development using Docker Compose
Cloud deployment to Kubernetes or App Services
Integration with CI/CD pipelines and Azure Container Registry
Seamless developer onboarding with reproducible environments

🐳 Every service is generated with fully working containerization support — including Dockerfiles, compose manifests, and readiness probes.

📦 Core Structure¶

Infrastructure/
└── DockerCompose/
    ├── docker-compose.yml
    ├── .env
    └── docker-compose.override.yml

Application/
└── MyService.Application/
    └── Dockerfile

⚙️ Template Parameters¶

Parameter	Description
`--Docker`	Enables Dockerfile generation and Docker Compose support
`--UsePulumi`	Generates container registry provisioning and tagging
`--UseOpenTelemetry`	Exposes `/metrics` and tracing endpoints
`--HealthCheck`	Adds health probes to compose and Dockerfile
`--HttpPort` / `--HttpsPort`	Allows port mapping customization

🛠️ Dockerfile Example (App Host)¶

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish "MyService.Application.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyService.Application.dll"]

✅ Supports multi-stage build
✅ Optimized for ACR push and Kubernetes usage
✅ Automatically includes .env and health probe support

🧪 docker-compose.yml¶

version: '3.9'
services:
  myservice:
    build:
      context: .
      dockerfile: Application/MyService.Application/Dockerfile
    ports:
      - "5000:80"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - DOTNET_RUNNING_IN_CONTAINER=true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health/ready"]
      interval: 10s
      timeout: 5s
      retries: 3

✅ Auto-configured for:

Local HTTPS
Hot reload
Environment overrides

🌐 Port Mapping¶

Host Port	Container
`5000`	`http://localhost` (default REST API)
`5001`	`https://localhost` (if enabled)
`9090`	`/metrics`, Prometheus
`8080`	Bot framework endpoint
`6379`	Redis sidecar (if enabled)

🧠 Runtime Containers Supported¶

Container Type	Used For
`Service Host`	Primary REST/gRPC/API service
`Worker Host`	Background jobs and consumers
`Bot Host`	Microsoft Bot Framework
`Dapr Sidecar`	Actor support, bindings, pub/sub
`Telemetry Agent`	OpenTelemetry Collector or Application Insights
`PostgreSQL/SQL Server`	Local DB testing
`MongoDB`	NoSQL scenarios
`Redis`	Caching, state, actor timer storage

📦 Build Targets¶

Context	Target
Local Dev	`docker-compose up --build`
Azure DevOps	`docker build . && docker push`
Pulumi IaC	`Pulumi.Azure.ContainerApp(...)`
Helm Chart	Ready-to-deploy for AKS / EKS

🧪 Testing and Debugging¶

Use Visual Studio Container Tools or VSCode Remote Containers
Includes debug-ready profiles in launchSettings.json
Health checks verified via /health/* endpoints
Logs exposed via stdout (structured JSON for Serilog)

🔐 Security & Secrets in Docker¶

Supports:
- .env injection for local secrets
- Azure Key Vault volume mounting (Kubernetes)
- Secret store or vault integration via Pulumi

✅ Never hardcodes secrets into Docker images ✅ Production config uses ASPNETCORE_ENVIRONMENT and per-container override

🧠 Agent Compatibility¶

Agents can:

Generate container builds in CI
Push to registry (ACR, GHCR, DockerHub)
Update Docker Compose files
Trigger semantic flows via container metadata
Auto-generate Helm or YAML manifests for each containerized microservice

✅ Summary¶

Container-first design using multi-stage Dockerfiles
Includes Docker Compose for local testing
Supports health checks, environment configs, and observability ports
Ready for:
- CI/CD
- Kubernetes
- Developer sandbox environments
- Used by both developers and ConnectSoft agents

☸️ Kubernetes and Helm Deployment Support¶

The ConnectSoft Microservice Template is designed for Kubernetes-first deployments, providing:

🧱 Minimal and extensible YAML manifests
🎛 Configurable Helm chart templates
📦 Container lifecycle hooks and health probes
🔐 Secure secret management
🔄 Integration with Pulumi, Azure AKS, and CI/CD pipelines

☁️ Kubernetes support ensures every microservice can scale, self-heal, and integrate in a cloud-native cluster.

📦 Included Artifacts¶

If --Docker and --UsePulumi are selected, the template generates:

Infrastructure/
└── Kubernetes/
    ├── base/
    │   ├── deployment.yaml
    │   ├── service.yaml
    │   ├── ingress.yaml
    │   └── secret.yaml
    └── helm/
        ├── Chart.yaml
        ├── values.yaml
        └── templates/

⚙️ Deployment Configuration¶

File	Purpose
`deployment.yaml`	Defines container spec, env, volumes, probes
`service.yaml`	Exposes app via ClusterIP, LoadBalancer, or NodePort
`ingress.yaml`	Adds optional routing via NGINX, Traefik, Istio
`secret.yaml`	Injects config via mounted secret or env var
`values.yaml`	Parameterizes Helm chart values
`Chart.yaml`	Helm chart metadata for packaging

🧩 Key Features Supported¶

Feature	Description
✅ Liveness/Readiness probes	`/health/live`, `/health/ready`
✅ Rolling updates	`readinessGate`, `rollingUpdate`
✅ CPU/Memory limits	Defined in values.yaml
✅ TLS + Ingress	With optional cert-manager annotations
✅ Sidecars	Dapr, OpenTelemetry, or logging sidecars included
✅ Affinity & NodeSelector	Optional anti-affinity rules
✅ Service Mesh	Istio/Linkerd compatibility (labels and annotations ready)

📐 Example Deployment Snippet¶

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myservice
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myservice
  template:
    metadata:
      labels:
        app: myservice
    spec:
      containers:
        - name: myservice
          image: myregistry.azurecr.io/myservice:1.0.0
          ports:
            - containerPort: 80
          livenessProbe:
            httpGet:
              path: /health/live
              port: 80
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 80

🧪 Helm Chart Structure¶

File	Purpose
`templates/deployment.yaml`	Templated Kubernetes deployment
`values.yaml`	Defines:

replicaCount
image.repository
env, resources, ingress | | Chart.yaml | Chart metadata | | templates/service.yaml | ClusterIP service | | templates/ingress.yaml | Optional HTTP routing |

✅ Supports CI/CD deployment via:

helm upgrade --install myservice ./helm --values values.prod.yaml

🔐 Secrets and Config Management¶

Method	Description
`envFrom: secretRef`	Mounts secret directly into container
Azure Key Vault	Injected via CSI driver
`configMap`	Mounts appsettings or values.yaml overrides

Secrets never stored in Git; injected via secure pipeline

🧠 Pulumi/Kubernetes Integration¶

If --UsePulumi is true:

Kubernetes manifests are provisioned using Pulumi YAML or TS
ACR registry image is published, tagged, and deployed
Environment-specific values are stored in stack configs

✅ Compatible with AKS, EKS, GKE, Minikube

🧠 Agent Usage and Automation¶

Agents can:

Update deployment replica count
Inject secrets during rollout
Monitor readiness via /health/ready
Execute rolling deployments with semantic change annotations
Trigger Helm chart generation dynamically

✅ Helm chart metadata includes semantic tags (e.g., version, role, edition)

📊 Observability with K8s¶

Health probes surface into:
- Prometheus scrape targets
- Azure App Insights
- Container logs collected via:
- FluentBit
- OpenTelemetry sidecars
- Loki/Grafana stack

✅ Summary¶

Fully prepared for Kubernetes deployment using:
- Base YAMLs
- Helm charts
- CI/CD pipeline support
- Includes:
- Readiness probes
- Secrets/config handling
- Sidecar and service mesh integration
- Compatible with:
- Agents
- Pulumi
- Azure DevOps, GitHub Actions

🏗️ Infrastructure as Code with Pulumi¶

The ConnectSoft Microservice Template optionally generates a complete Infrastructure as Code (IaC) project using Pulumi to:

Provision cloud-native resources for each microservice
Enable repeatable, automated environments (dev/staging/prod)
Integrate infrastructure into CI/CD workflows
Support both Azure and multi-cloud platforms

🧱 Pulumi is chosen for its modern language-first approach, modularity, and strong integration with Azure, Kubernetes, and container registries.

📦 Project Structure¶

Infrastructure/
└── Pulumi/
    ├── Pulumi.yaml
    ├── Pulumi.dev.yaml
    ├── index.ts
    ├── azure/
    │   ├── appservice.ts
    │   ├── containerregistry.ts
    │   ├── keyvault.ts
    │   ├── servicebus.ts
    │   ├── cosmosdb.ts
    │   └── monitoring.ts

✅ Each service template gets its own isolated Pulumi stack with environment support.

⚙️ Template Parameters¶

Parameter	Description
`--UsePulumi`	Adds Pulumi IaC project
`--UseApplicationInsights`	Deploys Azure Monitor with correlation ID tagging
`--UseAuthentication`	Registers App Registration and OIDC app
`--MessagingModelType`	Provisions RabbitMQ, Azure Service Bus, or topic queues
`--PersistenceModelType`	Deploys SQL, CosmosDB, or MongoDB instance
`--UseOpenAI`	Creates Azure OpenAI service or secret linkages
`--Docker`	Builds and pushes Docker image to ACR as part of the stack

🚀 Pulumi Resource Modules¶

Module	Description
`containerregistry.ts`	Creates ACR registry + access credentials
`appservice.ts`	Azure Web App / Container App for the service host
`servicebus.ts`	Topic, queue, and namespace provisioning
`cosmosdb.ts`	Database account and containers
`keyvault.ts`	Secure secret storage and identity injection
`monitoring.ts`	App Insights, Log Analytics, and telemetry wiring
`dns.ts`	Optional DNS A/CNAME records and certs

🧬 Example: Provisioned Stack¶

const app = new azure.appservice.ContainerApp("myservice", {
    resourceGroupName,
    image: "myregistry.azurecr.io/myservice:1.0.0",
    ingress: { external: true },
    environmentVariables: {
        "ASPNETCORE_ENVIRONMENT": "Production",
        "Jwt__Authority": keyVault.getSecret("Jwt__Authority")
    }
});

✅ All secrets loaded via Key Vault binding ✅ Output values are published to .env, Pulumi.dev.yaml, or Azure App Config

🛡️ Secrets & Identity¶

Secrets like:
- Jwt__Authority
- ServiceBus__ConnectionString
- OpenAI__ApiKey
- Are stored in:
- Pulumi secret config
- Azure Key Vault
- Kubernetes secrets (if applicable)

🧠 Multi-Stack and Environment Support¶

File	Description
`Pulumi.dev.yaml`	Dev configuration
`Pulumi.staging.yaml`	Stage/pre-prod config
`Pulumi.prod.yaml`	Production configuration
`Pulumi.yaml`	Stack metadata and backend settings

✅ Fully supports environment separation via pulumi stack select ✅ Compatible with GitHub Actions and Azure DevOps Pipelines

🧪 Testing and Preview¶

pulumi preview – dry-run the deployment
pulumi up – deploy changes to cloud
pulumi destroy – tear down service and all dependencies

✅ Safe, observable, and auditable

🧠 Agent Usage¶

ConnectSoft AI agents can:

Extend or regenerate Pulumi modules
Read provisioned outputs as environment inputs for apps
Generate .env or launchSettings.json with secrets
Use tags, annotations, and labels for planner optimization
Auto-bind DNS records and certificates via IaC

✅ Full traceability between code, infrastructure, and execution context

🔄 CI/CD Integration¶

Tool	Step
Azure DevOps	Pulumi CLI task or `bash` inline script
GitHub Actions	Pulumi Action + Azure login
Pulumi Cloud	Observability, auditing, access controls

✅ Summary¶

Full infrastructure automation with Pulumi
Generates Azure resources based on selected options
Supports:
- ACR
- App Service
- Service Bus
- Key Vault
- CosmosDB
- App Config
- Enables secure, repeatable, observable deployments

🚀 CI/CD Pipelines and DevOps Integration¶

The ConnectSoft Microservice Template includes built-in support for automated delivery pipelines, aligned with:

📦 Azure DevOps
🔁 GitHub Actions
🐳 Container-based build and release
🧪 Full test, lint, validate, and deploy flow
🧠 Agent-driven orchestration (pipeline-as-code)

🧩 Pipelines are designed to support multi-project solutions, multiple environments, and template-generated services at scale.

📂 Pipeline Artifacts Included¶

Infrastructure/
└── Pipelines/
    ├── azure-devops/
    │   ├── ci.yml
    │   ├── cd.yml
    ├── github-actions/
    │   ├── ci.yml
    │   ├── release.yml
    ├── templates/
    │   ├── dotnet-build.yml
    │   ├── docker-build.yml
    │   └── pulumi-deploy.yml

⚙️ Template Parameters¶

Parameter	Description
`--Docker`	Enables containerized builds and push stages
`--UsePulumi`	Includes Pulumi-based deploy stages
`--UseFeatureFlags`	Syncs flags with Azure App Configuration
`--MessagingModelType`	Adds infrastructure targets (e.g., RabbitMQ, Service Bus)
`--UseOpenTelemetry`	Adds trace publishing and exporter hooks
`--UseApplicationInsights`	Adds instrumentation output to App Insights
`--UseUnitTests`	Registers test discovery, coverage, and validation

🧪 CI Pipeline Stages (ci.yml)¶

Stage	Description
Checkout	Clones repo, validates Git state
Build	Runs `dotnet build` and/or Docker build
Test	Runs unit + integration tests
Lint	Code format, dependency check
Analyze	Optional SonarQube or Roslyn rules
Pack	Packages NuGet outputs (if any)
Publish Artifacts	`.nupkg`, coverage reports, logs

✅ Fully isolated with per-project build/test matrix

🚀 CD Pipeline Stages (cd.yml)¶

Stage	Description
Pull Image	Pulls image or artifact from registry
Pulumi Deploy	Provisions cloud infrastructure
Helm Deploy	(Optional) Deploy to Kubernetes
Post-Deploy Health	Polls `/health/ready` endpoint
Slack/Teams Notify	Sends result to release channels

✅ Can include multi-environment gate (e.g., dev → staging → prod) ✅ Compatible with service mesh, scaling rules, and rollout policies

🧪 Testing Pipeline Integration¶

Framework	Included
MSTest	✅
SpecFlow (BDD)	✅
xUnit (optional)	⬜️
Coverlet Coverage	✅ Output to Cobertura/LCOV
Architecture Tests	✅ Rules for layering, cyclic dependencies

📍 Results are exported to Azure DevOps test tab or GitHub Actions artifacts.

📦 Docker Registry Integration¶

Registry	Integration
Azure Container Registry (ACR)	`az acr login` and `docker push`
GitHub Container Registry (GHCR)	Auth via GitHub token
DockerHub	Env-based login and tagging

Tags typically follow:

myservice:1.0.0
myservice:2024.05.01-ci.1234

🔐 Secrets and Key Vault¶

Azure DevOps uses Key Vault Task to fetch secrets at runtime
GitHub Actions can:
- Use environment secrets
- Pull secrets via Pulumi stack config

🧠 AI Agent and Planner Integration¶

Agents can:

Inject pipeline variables or override task inputs
Trigger builds/releases via GitHub/DevOps APIs
Analyze failed builds and suggest corrections
Attach semantic metadata to pipeline runs (e.g., tags like ai-generated)
Generate post-run summaries or adaptive cards

✅ Used in continuous planning loops ✅ Skills and plugins map to each DevOps phase

✅ Summary¶

CI/CD pipelines for build, test, package, deploy
Supports:
- Azure DevOps
- GitHub Actions
- Pulumi + Helm + Docker
- Fully traceable, testable, and agent-aware
- Enables safe, scalable, and observable software delivery

🧪 Unit Testing, BDD, and Quality Gates¶

The ConnectSoft Microservice Template promotes test-first, specification-driven development, and includes:

✅ Unit tests for logic isolation
✅ BDD tests using SpecFlow for behavior verification
✅ Architecture rules for Clean Architecture enforcement
✅ Test coverage metrics with reporting integration
✅ CI-compatible quality gates (optional)

🧠 Testing infrastructure is designed to be automatable, AI-analyzable, and pipeline-ready.

📂 Test Project Structure¶

Testing/
├── UnitTests/
│   └── Domain/
│   └── Application/
├── AcceptanceTests/
│   └── Features/
│   └── Steps/
│   └── Hooks/
├── ArchitectureTests/
│   └── LayerRules/
│   └── DependencyGuards/

Each testing layer targets different responsibilities:

UnitTests → logic correctness
AcceptanceTests → feature specs (BDD)
ArchitectureTests → project structure & design discipline

🧪 Unit Tests (MSTest)¶

Examples:¶

Aggregate behavior (e.g., Order.Place() changes state)
Use case logic
Value object equality
Validators with edge cases

✅ Uses MSTest.TestFramework by default (can switch to xUnit/NUnit)

✅ FluentValidation Test Integration¶

var validator = new CreateOrderValidator();
var result = validator.TestValidate(input);
result.ShouldHaveValidationErrorFor(x => x.CustomerId);

📖 BDD Testing with SpecFlow¶

Included via AcceptanceTests project
SpecFlow used for:
- Domain workflows
- Event-driven scenarios
- End-to-end tests via REST/gRPC/Bot calls

Feature File Example:¶

Feature: Order Placement

Scenario: Place a new order
  Given the customer is registered
  And they add an item to the cart
  When they submit the order
  Then the order should be saved
  And an OrderPlacedEvent should be published

Step Definition:¶

[When(@"they submit the order")]
public async Task WhenTheySubmitOrder()
{
    var result = await _client.PostAsync("/api/orders", ...);
    result.EnsureSuccessStatusCode();
}

✅ Includes database fixture and test server for HTTP requests

🧩 Architecture Tests¶

Using NetArchTest.Rules:

Enforces:
- No references from Infrastructure → Domain
- Only Application can depend on DomainModel
- Projects match clean layering structure

Example:¶

Types.InAssembly(ApplicationAssembly)
  .Should()
  .NotHaveDependencyOn("InfrastructureModel")
  .Check()
  .IsSuccessful.Should().BeTrue();

📊 Code Coverage¶

Collected via coverlet.collector
Exported in CI as:
- Cobertura (Azure DevOps)
- LCOV (GitHub Actions)
- Visualized in:
- ReportGenerator
- Azure DevOps Test Tab
- SonarCloud (optional)

✅ Thresholds can be enforced (e.g., 80% min per project)

🧠 Quality Gates (Optional)¶

Tool	Role
SonarQube / SonarCloud	Coverage + duplicate code + complexity
Mutation Testing	Stryker.NET integration
Test Impact Analysis	Azure DevOps or GitHub caching
Security Scans	Optional static analysis (e.g., CredScan)

🧠 Agent Integration¶

Agents can:
- Create new unit tests based on use cases
- Generate .feature files from domain model
- Analyze test failures and recommend fixes
- Summarize test coverage gaps
- Identify critical paths for regression testing
- Inject tracing spans into test execution

✅ Test output is tagged with correlation ID, tenant ID, trace ID

✅ Summary¶

Full suite of automated tests:
- Unit
- BDD (SpecFlow)
- Architecture
- Coverage
- Aligns with CI/CD and AI observability
- Ensures code correctness, design discipline, and business alignment

📚 Structured Logging and Telemetry Enrichment¶

The ConnectSoft Microservice Template includes a structured, context-aware logging system designed to support:

✅ Consistent and machine-readable log entries
🧭 Correlation of logs with traces and metrics
📡 Multi-tenant and multi-service observability
🔁 Automatic enrichment with execution context
📥 Seamless integration with CI, AI agents, and distributed systems

📘 Logging is not just diagnostic — it is a source of truth for runtime decisions, telemetry, and auditing.

⚙️ Template Parameters¶

Parameter	Description
`--Logging`	`Serilog` (default), `Log4Net`, or `None`
`--OpenTelemetry`	Enables trace ID correlation in logs
`--UseApplicationInsights`	Routes logs to Azure Monitor
`--UseAuditNet`	Optional audit logging stream
`--UsePulumi`	Automatically configures sink per environment

✅ Default Logging Pipeline (Serilog)¶

Key Features:¶

✅ JSON-formatted logs
✅ Console + file + remote sink support
✅ Enriched with:
- TenantId
- CorrelationId
- TraceId
- UseCaseName
- Environment

📂 Logging Configuration Example¶

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "Enrich": [ "FromLogContext", "WithThreadId", "WithMachineName" ],
    "WriteTo": [
      { "Name": "Console" },
      { "Name": "File", "Args": { "path": "Logs/log.json", "rollingInterval": "Day" } }
    ]
  }
}

✅ Automatically injected via HostBuilderExtensions

🧪 Logging Example¶

{
  "timestamp": "2025-05-02T12:34:56Z",
  "level": "Information",
  "message": "Placing order {OrderId}",
  "orderId": "ORD-123",
  "correlationId": "ac3f4e18",
  "traceId": "00-abc123...",
  "tenantId": "tenant-x",
  "useCase": "PlaceOrder"
}

✅ Ready for indexing in:

Elasticsearch
Seq
Azure Monitor
Grafana Loki

🧠 Logging Enrichers¶

The template adds enrichers automatically for:

Enricher	Source
`CorrelationId`	`X-Correlation-ID` or traceparent
`TraceId`	OpenTelemetry span context
`TenantId`	Resolved via `TenantContext`
`UseCaseName`	Captured via pipeline execution metadata
`Environment`	From ASPNETCORE_ENVIRONMENT

🔌 Supported Sinks¶

Sink	Status
Console	✅ Included by default
File (Rolling)	✅ JSON format logs
Azure Monitor	✅ With `--UseApplicationInsights`
OpenTelemetry Exporter	✅ For trace-log integration
Elasticsearch / Seq / Loki	🔄 Optional, easily added via DI container

📏 Log Levels¶

Level	Use Case
`Verbose`	Debugging local development only
`Information`	Business-level operations (e.g., Order placed)
`Warning`	Retryable failures, fallback paths
`Error`	Unhandled exceptions, failed validation
`Fatal`	Startup errors, critical pipeline breakage

🧪 Testing Strategy¶

Validate structured output using:
- Serilog.TestLogger
- Console snapshot matching
- Log context assertion helpers
- BDD: capture logs in SpecFlow ScenarioContext
- Integration: assert logs appear in expected sink

🧠 Agent Capabilities¶

Agents can:

Inject or suggest new log events
Correlate logs with trace data
Generate summaries of past executions
Query logs for insights or triggers
Translate logs into adaptive cards (for bots or dashboards)

✅ SK plugins can consume log data directly as part of memory or prompt input

✅ Summary¶

Logging is structured, context-aware, and multi-sink ready
Fully aligned with:
- Correlation IDs
- Tenant metadata
- AI and telemetry workflows
- Enables real-time debugging, postmortem analysis, and intelligent orchestration

🔌 Integration Abstractions and Extensibility Points¶

The ConnectSoft Microservice Template provides a clean, composable, and abstracted integration layer that enables microservices to:

Connect to external systems (e.g., APIs, CRMs, payment providers)
Publish and consume integration events
Add or swap adapters without changing core business logic
Register client/service abstractions as reusable modules
Enable AI agents to extend integrations dynamically

🧩 Integration logic is modular, resides outside the domain, and is wired through standard interfaces and dependency injection.

📦 Core Integration Projects¶

Infrastructure/
├── ExternalApis/
│   ├── Braze/
│   ├── Segment/
│   └── Stripe/
├── Connectors/
│   ├── IHttpApiClient<TRequest, TResponse>
│   ├── IMessageDispatcher
│   └── IIntegrationPublisher

✅ Used by both humans and agents to integrate cleanly with external systems.

🧱 Key Abstractions Provided¶

Interface	Role
`IHttpApiClient<TRequest, TResponse>`	General-purpose typed HTTP integration
`IIntegrationPublisher`	Event dispatch abstraction (e.g., webhook, queue, third-party)
`IMessageDispatcher`	Command dispatcher for decoupled use cases
`INotificationDispatcher`	Email/SMS/push abstraction for alerts
`IExternalServiceClient`	Marker interface for API wrappers

🧩 Example: API Client Abstraction¶

public interface IBrazeClient
{
    Task SendUserProfileAsync(BrazeProfileRequest request, CancellationToken ct);
}

Registered via:

services.AddHttpClient<IBrazeClient, BrazeClient>()
        .AddPolicyHandler(ResiliencePolicies.WithRetry());

✅ Allows runtime configuration via IOptions<BrazeOptions> ✅ Can be mocked, tested, and traced

🛠️ Connector Pattern for External APIs¶

public class StripePaymentConnector : IPaymentGateway
{
    public Task<PaymentResult> ChargeAsync(PaymentRequest request)
    {
        // Stripe SDK or HTTP client logic
    }
}

Registered via:

services.AddScoped<IPaymentGateway, StripePaymentConnector>();

✅ Supports feature-driven swapping (e.g., replace Stripe with PayPal) ✅ Fully compatible with semantic AI agents

🔁 Message Dispatching & Integration Events¶

Integration events published via IIntegrationPublisher
Optional outbox pattern if using message bus
Webhook patterns also supported

await _integrationPublisher.PublishAsync(new AppointmentConfirmedEvent(...));

📬 Notification Dispatcher¶

await _notificationDispatcher.SendAsync(new NotificationPayload
{
    Type = NotificationType.Email,
    To = user.Email,
    TemplateId = "welcome-template",
    Data = new { FirstName = user.FirstName }
});

✅ Plug into:

SendGrid
MailKit
Twilio
Push Notification APIs

🧠 AI Agent and Planner Integration¶

Agents can:
- Register new integration clients
- Add connector metadata and test scaffolds
- Use adapters as callable skills via Semantic Kernel
- Wrap connectors with tracing, retries, and circuit breakers

✅ All connectors implement trace-friendly interfaces and support observability hooks

🧪 Testability & Isolation¶

Interfaces injected via DI
Use WireMock, MockHttp, or FakeConnector
Supported by unit tests, BDD steps, and SK simulations

📊 Observability¶

All integrations are:

Traced with OpenTelemetry spans
Logged using correlation ID and tenant metadata
Measured via custom metrics like:
- external_api_calls_total
- integration_failures_total

✅ Summary¶

Provides extensible integration layer with clearly separated concerns
Supports:
- External APIs
- Messaging gateways
- Notification systems
- Enables:
- Testability
- Observability
- Agent orchestration
- Ideal for connectors, CRM integrations, and AI-triggered workflows

📝 Documentation with MkDocs and Mermaid Diagrams¶

The ConnectSoft Microservice Template includes first-class documentation support using:

📚 MkDocs + Material for MkDocs
🧠 Mermaid diagrams-as-code
🗂 Agent- and human-readable structure
🔁 Auto-generated structure aligned with Clean Architecture and DDD

📘 Every generated service includes prebuilt, expandable documentation that scales with the project and supports autonomous agent navigation.

📦 Documentation Files¶

docs/
├── index.md
├── architecture.md
├── domain-model.md
├── use-cases.md
├── configuration.md
├── messaging.md
├── observability.md
└── diagrams/
    ├── domain-sequence.mmd
    └── architecture-structure.mmd

✅ Follows the same format as the main ConnectSoft platform docs.

⚙️ Template Parameters¶

Parameter	Description
`--UseDocumentation`	Enables documentation scaffold
`--UsePulumi`	Includes infra diagrams and deployment flows
`--UseOpenTelemetry`	Adds observability diagrams and spans
`--ActorModelType`	Adds actor flowchart diagram
`--ServiceModelType`	Includes API contract or HTTP sequence diagrams

📐 MkDocs Structure Example (`mkdocs.yml`)¶

site_name: MyService Docs
theme:
  name: material
nav:
  - Home: index.md
  - Architecture: architecture.md
  - Domain Model: domain-model.md
  - Messaging: messaging.md
  - Configuration: configuration.md
  - Observability: observability.md
  - Use Cases: use-cases.md
  - Diagrams:
      - Architecture: diagrams/architecture-structure.mmd
      - Sequence: diagrams/domain-sequence.mmd

✅ Automatically rendered into a Material Design static site

📊 Mermaid Diagram Support¶

Included via:
- docs/diagrams/*.mmd
- Mermaid plugin enabled in mkdocs.yml
- Supports:
- C4 diagrams
- Flowcharts
- Sequence diagrams
- State machines

Example: Architecture Structure Diagram¶

graph TD
  UI[API Host / Bot Host / Job Host]
  UI --> App[Application Layer]
  App --> Domain[DomainModel]
  App --> Infra[Infrastructure Layer]
  Infra --> DB[(Database)]
  Infra --> Bus[(Message Bus)]

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

Example: Domain Sequence¶

sequenceDiagram
  participant User
  participant Controller
  participant UseCase
  participant Repository

  User->>Controller: POST /orders
  Controller->>UseCase: Execute(CreateOrder)
  UseCase->>Repository: Save(Order)
  Repository-->>UseCase: OrderId
  UseCase-->>Controller: OrderCreated

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

✅ Can be rendered inline or embedded in pages

📖 DDD Support in Docs¶

Each template includes generated docs for:

Section	Source
`domain-model.md`	From `EntityModel`, `ValueObjects`, `Aggregates`
`use-cases.md`	Extracted from `DomainModel` + `ApplicationModel`
`messaging.md`	Event and command contracts
`observability.md`	Trace, metric, log structure
`configuration.md`	From `Options/` + appsettings structure

🧠 Agent Compatibility¶

AI agents can:
- Navigate the docs programmatically
- Extract metadata for execution graphs
- Render new diagrams dynamically
- Insert AI-generated sections into Markdown
- Summarize structure for planning flows

✅ All documentation is AI-parsable and navigable ✅ Skills and planners can ingest Mermaid, Markdown, and YAML structure

🧪 Developer Usage¶

Run mkdocs serve to preview locally
Publish to:
- GitHub Pages
- Azure Static Web Apps
- docs.connectsoft.dev (agent-published)

✅ Works inside containerized dev environment

✅ Summary¶

The template includes ready-to-use, styled, agent-compatible documentation
Powered by:
- MkDocs
- Material UI
- Mermaid
- Supports:
- Clean Architecture
- Use cases
- Sequence flows
- Deployment diagrams
- Ideal for both developer onboarding and agent orchestration

📢 Domain Events, Outbox, and Event Publication¶

The ConnectSoft Microservice Template provides first-class support for domain event propagation and outbox-based message publishing to ensure:

✅ Event-Driven Architecture (EDA) consistency
🔄 Reliable messaging without data loss
🧱 Clean separation between domain and infrastructure
🧠 Agent-traceable events across services

🧩 Domain events are raised in the domain layer, collected in the application layer, and dispatched in the infrastructure layer via configurable buses.

🔁 Domain Event Lifecycle¶

sequenceDiagram
  participant Domain as Aggregate
  participant Collector as IEventCollector
  participant App as UseCaseHandler
  participant Bus as EventPublisher

  Domain->>Collector: AddDomainEvent()
  Collector-->>App: CollectUnpublishedEvents()
  App->>Bus: Publish(events)
  Bus-->>Infra: Dispatch to bus or outbox

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

📦 Event Publication Projects¶

Project	Description
`DomainModel`	Defines `IDomainEvent`, domain events
`ApplicationModel`	Collects uncommitted events during use case execution
`InfrastructureModel`	Publishes events via bus, outbox, or webhook
`MessagingModel`	Defines externalized integration events (pub/sub)

🧱 Domain Event Declaration¶

public record OrderPlacedEvent(OrderId Id, DateTime Timestamp) : IDomainEvent;

Raised inside aggregates:

AddDomainEvent(new OrderPlacedEvent(Id, DateTime.UtcNow));

✅ Stored temporarily in memory via IEventCollector ✅ Published after successful unit of work completion

🔄 Outbox Pattern (Optional)¶

When enabled (e.g., via MassTransit or NServiceBus):

Domain events are persisted in an outbox table or collection
A background job or transactional bus middleware then dispatches them
Ensures no message loss on crashes or rollback

Benefits:¶

Atomic with DB write
Retry-safe
Message deduplication support
Works with SQL, Mongo, or Cosmos

🛠 Bus Dispatchers¶

Bus	Dispatcher
MassTransit	`IEventPublisher` → `Publish<T>()` or `Send<T>()`
NServiceBus	`IMessageSession` → `Publish()`
Dapr (optional)	HTTP call to pub/sub binding
Webhook	`IWebhookDispatcher` or custom client integration

🔌 Integration Event Example¶

public record OrderConfirmedIntegrationEvent(string OrderId, string Email) : IIntegrationEvent;

Enriched with TenantId, CorrelationId, TraceId
Mapped from domain event via handler or converter

✅ Enables internal → external message separation

📊 Observability¶

Every published event is:

🔎 Logged (structured)
📡 Traced with OpenTelemetry span: event.publish.{eventName}
🧪 Measured (e.g., events_published_total, event_latency_seconds)
🧠 Tagged with:
- event_type
- tenant
- trigger_source (e.g., usecase, job, actor)

🧪 Testing Strategy¶

Level	Test Type
Domain	Verify `AddDomainEvent()` in aggregate behavior tests
Application	Assert that events are collected in `IEventCollector`
Infrastructure	Test bus interaction via `TestHarness` or spy
BDD	Assert `OrderPlacedEvent` is published on scenario success

🧠 AI Agent Support¶

Agents can:

Inspect DomainModel.yaml to identify events
Suggest new event listeners, projections, or pub/sub flows
Auto-generate integration event adapters
Record and trace events as part of semantic execution graph
Visualize system behavior from event graph

✅ Fully compatible with planner reasoning ✅ Future roadmap: temporal event graph summarization

✅ Summary¶

Domain events are:
- Raised in aggregates
- Collected in memory
- Published after success
- Outbox pattern is bus-agnostic and reliable
- Metrics, traces, and logs support full observability
- Used for:
- EDA flows
- Event sourcing
- AI integration
- External pub/sub systems

🌐 API Gateway and Edge Routing Integration¶

The ConnectSoft Microservice Template integrates seamlessly with API gateway patterns, providing a unified approach for:

🚪 Service entrypoint routing
🔐 Centralized authentication and authorization
🧭 Request transformation and enrichment
📊 Aggregated observability and telemetry
🎯 Multi-tenant edge segmentation

🔄 Supports out-of-the-box compatibility with YARP, Azure API Management, NGINX Ingress, and custom reverse proxies.

📦 Gateway Models Supported¶

Gateway	Purpose
YARP (ASP.NET Core)	Developer-friendly, pluggable reverse proxy
Azure API Management	Enterprise-grade, secure API publication
NGINX / Traefik	Kubernetes ingress controllers
Custom Gateways	Optional ConnectSoft-built proxies or orchestrators

⚙️ Template Parameters¶

Parameter	Description
`--ServiceModelType`	Required for exposed APIs (REST/gRPC/GraphQL)
`--UseAuthentication`	Enables gateway-based auth passthrough
`--UsePulumi`	Can provision API Management or Ingress
`--HttpPort` / `--HttpsPort`	Maps container to edge gateway route
`--FeatureFlags`	Enables edge feature routing by edition/tenant

🧭 YARP (Reverse Proxy in .NET)¶

Sample YARP config:¶

{
  "ReverseProxy": {
    "Routes": {
      "orders": {
        "ClusterId": "orders",
        "Match": { "Path": "/orders/{**catch-all}" }
      }
    },
    "Clusters": {
      "orders": {
        "Destinations": {
          "orderApp": { "Address": "http://orders-service" }
        }
      }
    }
  }
}

✅ Edge routing with optional tenant and path filtering ✅ Runs as dedicated ASP.NET Core app or within gateway-hosted containers

🧩 Azure API Management Integration¶

If --UsePulumi and --UseAuthentication:

Provisions:
- API registration (OpenAPI import)
- Product assignment
- Subscription key enforcement
- Supports:
- OAuth2 bearer validation
- Policy-based header transformation
- Rate limiting and usage quotas

✅ Integrates with ConnectSoft SaaS edition model for plan-based API tiers

🛡️ Gateway Security¶

Feature	Supported
JWT passthrough	✅ via header propagation
Role-based blocking	✅ via route policies
Tenant segmentation	✅ via header/token claim mapping
IP filtering / CORS	✅ configured per edge
Rate limiting	✅ via API Management or YARP middleware

🧪 Route Testing & Edge Validation¶

Scenario	Test Tool
Path routing	Postman + YARP test profile
Auth passthrough	JWT token with roles + tenant claim
gRPC proxying	gRPC-Web with edge config
Swagger publication	Import OpenAPI into API Management
Ingress traffic	K8s + NGINX with `/health/ready` check

📊 Observability from Gateway¶

Propagates X-Correlation-ID, X-Tenant-ID, traceparent
Logs edge telemetry via:
- Azure Monitor
- Serilog sink
- YARP diagnostics
- Metric endpoints exposed to:
- Prometheus
- API Management Analytics
- Grafana dashboards

🧠 AI Agent Usage¶

Agents can:

Generate gateway route definitions from ServiceModel.yaml
Bind OpenAPI specs to edge entries
Detect misrouted or missing services via probing
Extend edge configuration for A/B testing, Canary deploys
Recommend security policies or JWT validation rules

✅ AI-aware services can self-register at the gateway via planner hooks

✅ Summary¶

ConnectSoft microservices integrate with standard API gateways
Supports:
- YARP (reverse proxy)
- Azure API Management
- K8s ingress controllers
- Enables:
- Auth, rate limiting, tenant routing
- Secure edge interfaces
- AI-assisted deployment and API surfacing

🧱 Finalization, Use Cases, and Extensibility Paths¶

This final section consolidates the usage patterns, extensibility strategies, and real-world scenarios that the ConnectSoft Microservice Template supports.

It highlights how the template scales from a single service to a multi-agent, multi-tenant SaaS platform, including:

🧠 Human and agent workflows
🔁 Service evolution and modularity
🌍 Industry-aligned use cases
🔌 Plugin and extension options
📈 Future-forward integration paths

🧭 Usage Scenarios¶

Scenario	Description
Domain-Oriented Microservice	Aggregates, use cases, DDD events, REST/gRPC interface
Bot-Powered UX	Bot Framework dialogs + Semantic Kernel skills
AI-Centric Service	Semantic Kernel planner, skills, memory, prompt chaining
Workflow/Saga Coordinator	Event-driven + actor-based + background jobs
Federated Identity Gateway	OAuth2 integration with multi-tenant awareness
Composable SaaS Feature	Embedded within larger SaaS platform with edition control

🧱 Extensibility Options¶

Area	Extension Path
Persistence	Add new database (e.g., DynamoDB, CockroachDB) via new `PersistenceModel.*` project
Messaging	Integrate Kafka, Azure Event Grid, or Google Pub/Sub adapters
Actor Models	Extend to Akka.NET, Proto.Actor, or Project Tye
Authentication	Add multi-IDP federation, SCIM, SAML integration
AI Skills	Auto-register from external plugins, graphQL schemas, OpenAPI endpoints
Gateway	Add GraphQL Federation, YARP clustering, or API monetization tiers

✅ All extensions follow a plugin-first, decoupled architecture

🧠 Agent-Driven Lifecycles¶

Agents can:

Use the template as code scaffolding source
Dynamically configure feature toggles, database types, message buses
Modify documentation, diagrams, and config in response to design changes
Generate infrastructure, integration tests, and observability policies
Trigger full microservice generation via MCP or planner

🧠 Every microservice is agent-compatible by design, including all trace, config, and interface metadata.

🌍 Real-World Use Cases Enabled¶

Domain	Use Case
Insurance	Claims engine, policy management, fraud detection
Healthcare	Appointment service, EHR sync, lab report coordination
Education	Student progress tracker, chatbot tutor, AI-based grading
E-commerce	Order service, inventory actor, payment integration
Marketing	Event router, CRM integration, Segment/Braze sync
Finance	Portfolio simulator, billing engine, OpenAI financial insights

📐 Example Agent Execution Plan¶

agent: microservice-generator
input:
  AggregateRoot: Order
  PersistenceModel: NHibernate
  MessagingModel: MassTransit
  ActorModel: Orleans
  UseSemanticKernel: true
output:
  Folder: /src/OrderService
  DeploymentTarget: Kubernetes
  GitIntegration: Azure DevOps
  Observability: Prometheus + Grafana

✅ Fully driven by planner → template → orchestrator → GitOps → deployment

🧩 Extensible Composition Units¶

Type	Component
Aggregate	`EntityModel` + `DomainModel`
API Mode	`ServiceModel.*`
Job	`SchedulerModel.*`
Actor	`ActorModel.*`
Integration	`ExternalApis/Connector.cs`
Test	`SpecFlow Feature + Step`
Infra	`Pulumi Stack + Helm Chart`

All components are optional, replaceable, and composable.

✅ Summary¶

The ConnectSoft Microservice Template is a blueprint for scalable, intelligent, observable microservices
Designed for:
- Enterprise SaaS
- Agentic automation
- Cloud-native operations
- AI integration
- Supports rapid generation, deep customization, and safe evolution
- Works in harmony with ConnectSoft agents, DevOps pipelines, and real-world engineering teams

🧩 ConnectSoft Microservice Template¶

🚀 Introduction¶

🎯 Purpose¶

🧱 Architectural Foundations¶

🧬 Composition & Solution Structure¶

🧠 Generator & Automation Flow¶

⚙️ CLI Template Summary¶

🧪 Included Best Practices¶

✅ Summary¶

⚙️ Template Generation and Parameters¶

🧩 Installation and Usage¶

🔧 Install from NuGet / Azure DevOps Feed¶

🚀 Generate a new service¶

📌 Template Parameters Overview¶

🔁 Conditional Inclusion¶

🧠 AI-Driven Parameter Selection¶

📦 Output Example (when fully enabled)¶

✅ Summary¶

🧱 Supported Architectures and Runtime Models¶

🧱 Clean Architecture¶

🧠 Domain-Driven Design (DDD)¶

🕸️ Event-Driven Architecture (EDA)¶

🧠 Actor Model Support¶

🔄 Background Execution Models¶

🌐 API Surface Options¶

📦 Multi-Host Runtime Models¶

🧠 Semantic Kernel AI Support¶

✅ Summary¶

🏗️ Solution Structure and Project Breakdown¶

🗂️ Tree-Based Structure (Simplified)¶

🧱 Core Layers¶

🔹 Common Layer¶

🔹 Domain Layer¶

🔹 Persistence Layer¶

🔌 Integrations & Interfaces¶

🔹 Messaging¶

🔹 Actor Model¶

🔹 ServiceModel (API)¶

🔹 Scheduler¶

🔹 AI and Bot¶

🧩 Application Layer¶

🏗️ Infrastructure¶

✅ Testing Layer¶

🧭 Architecture & Documentation¶

🧪 Traceability and Design Discipline¶

✅ Summary¶

🧠 Domain Layer and DDD Foundation¶

🧱 DDD Tactical Patterns Supported¶

📦 Projects Involved¶

📂 Folder Structure Example¶

📌 Aggregate Example¶

📚 FluentValidation Integration¶

📤 Domain Events¶

🧠 Use Case Model¶

🔄 Specification Pattern¶

🧪 Testing Focus¶

✅ Summary¶

🗃️ Persistence Layer and Data Models¶

🧱 Core Projects¶

⚙️ Configuration Parameters¶

🧩 Repository and Specification Pattern¶

🗂️ NHibernate ORM Support¶

🍃 MongoDB Support¶

🗃️ Migrations Support¶

🧪 Testing Utilities¶

🧠 AI Usage¶

✅ Summary¶

📡 Messaging Layer and Event-Driven Patterns¶

📦 Core Projects¶

⚙️ Template Parameters¶

🧩 Messaging Model Structure¶

📂 MessagingModel/¶

🔁 MassTransit Flow Model¶

✅ Features:¶

🧰 Configuration via MassTransitOptions¶

📦 NServiceBus Flow Model¶

✅ Features:¶

🧠 Domain Event Integration¶

🔁 Saga Orchestration¶

🧪 Testing Support¶

🧰 Configuration via `MassTransitOptions`¶