Agent Microservice Standard Blueprint¶

This document defines the standard blueprint that agents follow when creating microservices in the ConnectSoft AI Software Factory. It is written for architects and engineers understanding the structure, patterns, and conventions of Factory-generated microservices.

Every microservice generated by the Factory follows a standard blueprint: Domain / Application / Infrastructure / API / Tests structure. This consistency enables agents to generate code predictably, makes the codebase maintainable, and ensures architectural safety.

Important

The standard blueprint is not optional—it's enforced by templates and agent constraints. This consistency is what makes agent generation safe and predictable. All Factory-generated microservices follow this blueprint.

Goals of the Blueprint¶

The standard blueprint ensures:

Clean Architecture & DDD¶

Dependency inversion - Inner layers don't depend on outer layers
Layer separation - Clear boundaries between Domain, Application, Infrastructure, API
Testability - Each layer can be tested independently
Bounded contexts - Clear domain boundaries and ubiquitous language

Multi-Tenant Ready¶

Tenant isolation - Every layer handles tenant context
Tenant-aware repositories - Data access respects tenant boundaries
Tenant context propagation - Context flows through all layers
Tenant-scoped queries - All queries filtered by tenant

Event-Driven Friendly¶

Domain events - Entities emit domain events
Integration events - Services publish integration events
Event handlers - Services subscribe to events
Event sourcing support - Optional event sourcing patterns

Observability by Default¶

Structured logging - All layers log with correlation IDs
Distributed tracing - OpenTelemetry tracing built-in
Metrics collection - Performance and business metrics
Health checks - Built-in health check endpoints

Security-First¶

Authentication - OAuth2/OpenID Connect integration
Authorization - Role-based and resource-based authorization
Input validation - All inputs validated
Secure defaults - Security best practices enforced

Layers and Structure¶

Every microservice follows this layered structure:

flowchart TD
    subgraph "API Layer"
        API[Controllers<br/>Request/Response Models<br/>API Documentation]
    end

    subgraph "Application Layer"
        UC[Use Cases<br/>Workflows<br/>Application Services]
        DTO[DTOs<br/>Mappers]
    end

    subgraph "Domain Layer"
        E[Entities<br/>Aggregates]
        VO[Value Objects]
        DS[Domain Services]
        DE[Domain Events]
    end

    subgraph "Infrastructure Layer"
        R[Repositories<br/>Data Access]
        MSG[Messaging<br/>Event Bus]
        EXT[External Services<br/>HTTP Clients]
        CFG[Configuration]
    end

    subgraph "Tests Layer"
        UT[Unit Tests<br/>Domain & Application]
        IT[Integration Tests<br/>API & Infrastructure]
        AT[Acceptance Tests<br/>End-to-End]
    end

    API -->|Calls| UC
    UC -->|Uses| E
    UC -->|Uses| VO
    UC -->|Uses| DS
    UC -->|Emits| DE
    UC -->|Uses| R
    UC -->|Uses| MSG
    UC -->|Uses| EXT

    R -->|Implements| E
    MSG -->|Publishes| DE
    EXT -->|Calls| CFG

    UT -.->|Tests| E
    UT -.->|Tests| UC
    IT -.->|Tests| API
    IT -.->|Tests| R
    AT -.->|Tests| API

    style E fill:#2563EB,color:#fff
    style UC fill:#4F46E5,color:#fff
    style API fill:#10B981,color:#fff
    style R fill:#EAB308,color:#fff

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

Domain Layer¶

Purpose: Core business logic, independent of infrastructure and frameworks.

Components:

Entities - Domain objects with identity and lifecycle
Aggregates - Clusters of entities treated as a unit
Value Objects - Immutable objects defined by their attributes
Domain Services - Domain logic that doesn't belong to a single entity
Domain Events - Events that represent something that happened in the domain

Dependencies: None (pure domain logic)

Example: Invoice entity, Money value object, InvoiceCreated domain event

Application Layer¶

Purpose: Use cases and application workflows, orchestrates domain logic.

Components:

Use Cases - Application-specific workflows
Application Services - Orchestration of domain logic
DTOs - Data transfer objects for API communication
Mappers - Convert between domain objects and DTOs

Dependencies: Domain layer only

Example: CreateInvoiceUseCase, InvoiceDto, InvoiceMapper

Infrastructure Layer¶

Purpose: Technical implementations, external integrations, data access.

Components:

Repositories - Data access implementations
Messaging - Event bus, message queues
External Services - HTTP clients, third-party integrations
Configuration - App settings, feature flags

Dependencies: Domain and Application layers

Example: InvoiceRepository, EventBus, PaymentGatewayClient

API Layer¶

Purpose: HTTP/gRPC endpoints, request/response handling.

Components:

Controllers - HTTP endpoint handlers
Request/Response Models - API contract models
API Documentation - OpenAPI/Swagger specs

Dependencies: Application layer only

Example: InvoiceController, CreateInvoiceRequest, InvoiceResponse

Tests Layer¶

Purpose: Comprehensive test coverage for all layers.

Components:

Unit Tests - Test domain and application logic in isolation
Integration Tests - Test API and infrastructure integrations
Acceptance Tests - End-to-end tests for user stories

Dependencies: All layers (for testing)

Example: InvoiceTests, InvoiceControllerTests, CreateInvoiceAcceptanceTests

Cross-Cutting Concerns¶

All microservices include these cross-cutting concerns:

Logging¶

Structured logging - JSON-formatted logs with correlation IDs
Log levels - Debug, Info, Warning, Error
Context propagation - Correlation IDs flow through all layers
Library: ConnectSoft.Extensions.Logging

Tracing¶

Distributed tracing - OpenTelemetry tracing
Span creation - Spans for all operations
Trace context - Trace IDs propagated across services
Library: ConnectSoft.Extensions.OpenTelemetry

Metrics¶

Performance metrics - Request duration, throughput
Business metrics - Domain-specific counters
Health metrics - Service health indicators
Library: ConnectSoft.Extensions.OpenTelemetry

Validation¶

Input validation - All API inputs validated
Domain validation - Domain rules enforced
Library: FluentValidation or similar

Error Handling¶

Exception handling - Centralized exception handling
Error responses - Consistent error response format
Error logging - All errors logged with context

Feature Flags¶

Feature flag support - Toggle features without deployment
Library: ConnectSoft.Extensions.Config

Configuration¶

External configuration - Configuration from external source
Environment-specific - Different configs per environment
Library: ConnectSoft.Extensions.Config

Default Integrations¶

All microservices include these default integrations:

Azure DevOps¶

CI/CD pipelines - YAML pipelines for build, test, deploy
Work items - Epics, user stories, tasks linked to code
Repositories - Code stored in Azure DevOps repos
Boards - Work tracking and project management

Observability Stack¶

OpenTelemetry - Distributed tracing and metrics
Structured logging - JSON logs with correlation IDs
Health checks - Built-in health check endpoints
Dashboards - Pre-configured monitoring dashboards

Messaging/Event Bus¶

Azure Service Bus - Event publishing and subscription
Event handlers - Subscribe to integration events
Event publishing - Publish domain and integration events
Library: ConnectSoft.Extensions.Messaging

Security¶

OAuth2/OpenID Connect - Authentication integration
Authorization - Role-based and resource-based authorization
Tenant context - Tenant isolation and context propagation
Library: ConnectSoft.Extensions.OAuth2, ConnectSoft.Extensions.Identity

Example Generated Service Structure¶

Here's the directory structure for a generated microservice:

InvoiceService/
├── src/
│   ├── InvoiceService.Api/
│   │   ├── Controllers/
│   │   │   └── InvoiceController.cs
│   │   ├── RequestModels/
│   │   │   └── CreateInvoiceRequest.cs
│   │   ├── ResponseModels/
│   │   │   └── InvoiceResponse.cs
│   │   └── InvoiceService.Api.csproj
│   │
│   ├── InvoiceService.Application/
│   │   ├── UseCases/
│   │   │   └── CreateInvoiceUseCase.cs
│   │   ├── DTOs/
│   │   │   └── InvoiceDto.cs
│   │   ├── Mappers/
│   │   │   └── InvoiceMapper.cs
│   │   └── InvoiceService.Application.csproj
│   │
│   ├── InvoiceService.Domain/
│   │   ├── Entities/
│   │   │   └── Invoice.cs
│   │   ├── ValueObjects/
│   │   │   └── Money.cs
│   │   ├── DomainServices/
│   │   │   └── InvoiceCalculationService.cs
│   │   ├── DomainEvents/
│   │   │   └── InvoiceCreated.cs
│   │   └── InvoiceService.Domain.csproj
│   │
│   └── InvoiceService.Infrastructure/
│       ├── Repositories/
│       │   └── InvoiceRepository.cs
│       ├── Messaging/
│       │   └── EventBus.cs
│       ├── ExternalServices/
│       │   └── PaymentGatewayClient.cs
│       └── InvoiceService.Infrastructure.csproj
│
├── tests/
│   └── InvoiceService.Tests/
│       ├── Unit/
│       │   ├── Domain/
│       │   │   └── InvoiceTests.cs
│       │   └── Application/
│       │       └── CreateInvoiceUseCaseTests.cs
│       ├── Integration/
│       │   └── InvoiceControllerTests.cs
│       └── Acceptance/
│           └── CreateInvoiceAcceptanceTests.cs
│
├── pipelines/
│   └── azure-pipelines.yml
│
└── docs/
    ├── architecture.md
    ├── README.md
    └── adr/
        └── 0001-invoice-service-design.md

Explanation:

src/ - Source code organized by layer
InvoiceService.Api - API layer (controllers, request/response models)
InvoiceService.Application - Application layer (use cases, DTOs)
InvoiceService.Domain - Domain layer (entities, value objects, domain events)
InvoiceService.Infrastructure - Infrastructure layer (repositories, messaging, external services)
tests/ - Test projects organized by test type
pipelines/ - CI/CD pipeline definitions
docs/ - Documentation (architecture, ADRs)

Microservice Template - Technical template specification
Clean Architecture & DDD - Architectural principles
Event-Driven Mindset - Event-driven patterns
Cloud-Native Mindset - Cloud-native patterns
Technology Stack - Technologies and frameworks used

Agent Microservice Standard Blueprint¶

Goals of the Blueprint¶

Clean Architecture & DDD¶

Multi-Tenant Ready¶

Event-Driven Friendly¶

Observability by Default¶

Security-First¶

Layers and Structure¶

Domain Layer¶

Application Layer¶

Infrastructure Layer¶

API Layer¶

Tests Layer¶

Cross-Cutting Concerns¶

Logging¶

Tracing¶

Metrics¶

Validation¶

Error Handling¶

Feature Flags¶

Configuration¶

Default Integrations¶

Azure DevOps¶

Observability Stack¶

Messaging/Event Bus¶

Security¶

Example Generated Service Structure¶

Related Documents¶