🧱 Strategic Use of Domain-Driven Design & Clean Architecture¶

🧠 Introduction¶

In ConnectSoft, Domain-Driven Design (DDD) and Clean Architecture are not merely coding patterns — they are strategic execution principles. These principles provide the structure, boundaries, and semantics that intelligent agents need to autonomously generate safe, scalable, and modular software systems.

“Without domain boundaries and clean layering, agents produce chaos. With them, they produce composable systems.”

This document outlines how and why these principles are applied throughout the platform — to support agent collaboration, blueprint alignment, tenant isolation, and event-driven automation.

🧩 Why These Principles Matter¶

Capability	Enabled by DDD / Clean Architecture
✅ Agent-Oriented Generation	Clear layering guides code and test output per agent
✅ Blueprint-to-Code Mapping	Domain models align with bounded contexts and service contracts
✅ Multi-Agent Safety	Domain events and aggregates prevent logic scattering
✅ Observability and Testability	Each layer has traceable responsibilities
✅ Tenant-Scoped Automation	Contexts remain isolated and cleanly injectable

🧱 DDD in ConnectSoft = Strategic Boundaries¶

Domain-Driven Design provides:

Bounded Contexts → Modular blueprints and service segmentation
Aggregates → Safety and encapsulation of core logic
Value Objects → Repeatable templates across services
Domain Events → Signal generation for orchestration
Ubiquitous Language → Structured AI input for accurate modeling

These patterns make it possible for agents to generate domain-centric services, not just technical scaffolds.

🧼 Clean Architecture = Agent-Friendly Layering¶

Clean Architecture enables:

Clear separation of concerns
Dependency inversion (no leakage between infrastructure and domain)
Scaffolding by layer (app, domain, infra)
Replacement of adapters and ports by agents without risk
Deterministic file placement and artifact verification per skill

"The structure exists so that agents don’t need to think — they only need to follow contracts."

📦 Outcome: Software That’s Modular, Maintainable, and Machine-Generated¶

Using DDD and Clean Architecture:

Every blueprint knows where each artifact belongs
Every agent knows what layer it can modify
Every coordinator knows when to trigger each skill
Every artifact is aligned with purpose, context, and lifecycle phase

📘 Covered in This Document¶

In the following cycles, we’ll explore:

How DDD shapes modular blueprints
How Clean layering is enforced by templates
How agents generate domain models, test logic, and contracts
How CQRS, specifications, events, and anti-corruption layers are used to preserve modularity

✅ Summary¶

ConnectSoft uses DDD and Clean Architecture as automation enablers, not just developer discipline
These principles define how blueprints are structured, how agents behave, and how flows scale safely
Every module, service, and tenant is powered by these patterns

🤖 Strategic Role in AI-First Automation¶

In ConnectSoft, DDD and Clean Architecture aren’t used to make life easier for developers — they’re used to make life possible for AI agents. Without these principles, agents can’t operate autonomously, consistently, or safely.

“Agents don’t guess where to put logic — they follow architectural rules that enforce structure and meaning.”

These principles allow the platform to scale intelligent automation across hundreds of services, because they define predictable, constraint-driven environments that agents can understand, navigate, and execute in.

🧠 Why AI Needs Structure¶

AI agents operate based on:

Prompts
Skills
Contracts
Blueprint mappings
Domain context

If those inputs are unstructured, inconsistent, or chaotic, agent outputs become:

Brittle
Duplicated
Misplaced
Invalid
Dangerous (e.g., broken multi-tenant boundaries)

Clean Architecture and DDD solve that problem at the source.

🧩 Strategic Advantages for AI-Driven Automation¶

Capability	Enabled by DDD & Clean
🧱 Blueprint-to-code mapping	Bounded contexts → service structure → folders → agents
⚙️ Skill-to-layer mapping	`GenerateHandler` → App Layer, `EmitDomainEvent` → Domain Layer
🛡 Scoped decision boundaries	No agent emits logic outside its assigned layer or context
🧪 Automated validation	Schema validators, contract matchers, and blueprint linter rules
📦 Artifact traceability	Every output linked to layer, skill, traceId, and DDD concept
🔁 Retry and regeneration	Idempotent scaffolds via deterministic structure
🧠 Prompt precision	“Generate command handler in App layer for Booking aggregate” → 100% precise

📘 Example: Blueprint Line → Agent Skill Mapping¶

aggregate: Booking
command: BookAppointment
layer: Application
output: BookAppointmentHandler.cs

→ Backend Developer Agent executes GenerateHandler skill, emitting the correct class in the correct folder using known architectural constraints.

🔐 Architecture as an Enforcement Engine¶

Without DDD/Clean:

Agents would overlap responsibility
Output folders would be inconsistent
Business logic would leak into infrastructure
Domain contracts would drift from blueprints
Prompt reuse and skill reuse would break down

✅ Clean Architecture solves this by ensuring each agent owns a lane and never crosses it.

🧠 Orchestrator Benefits¶

Clean layering and DDD modeling allows the orchestration layer to:

Compose execution plans by blueprint layer
Retry skills based on layer-specific errors (e.g., test → domain logic → fix)
Block release if a layer’s outputs are missing or unverified
Generate dependency graphs (e.g., App depends on Domain, Infra is last)

✅ Summary¶

DDD and Clean Architecture enable AI-first automation by creating clear boundaries, safe scaffolds, and predictable mappings
They ensure agents can work independently but consistently across modules
These principles are embedded into every ConnectSoft template, blueprint, and coordinator

🧩 Domain-Driven Modularization¶

In ConnectSoft, bounded contexts are the foundation of modularity. They define the scope of autonomy for a module, microservice, or blueprint — and they align perfectly with the goals of scalable, agent-driven software generation.

“The bounded context is the unit of generation, testing, deployment, and ownership.”

This makes Domain-Driven Design (DDD) not just a modeling strategy — but a modularization engine for the AI Software Factory.

🧠 What Is a Bounded Context?¶

A bounded context is a self-contained domain boundary where:

Language is consistent and local
Models are stable and independent
Integration happens via contracts and events
No external assumptions leak in
Code, tests, and flows are owned and isolated

In ConnectSoft, every blueprint, agent flow, and deployment unit maps to a bounded context.

📦 Module Structure by Context¶

Each bounded context is mapped to:

/modules/
  Booking/
    /Application/
    /Domain/
    /Infrastructure/
    /Tests/
    /Docs/
    /Contracts/

This lets agents work in bounded subgraphs of the system without needing to understand the whole platform.

🔁 Event-Driven Context Boundaries¶

Bounded contexts:

Emit domain events that cross boundaries (e.g., AppointmentBooked)
Consume external events via anti-corruption layers or message handlers
Never call each other directly (even via code)

This structure enables agents to be context-local and event-connected — the key to massive agent parallelism.

📘 Blueprint Example with Context Tag¶

service: BookingService
boundedContext: Booking
domain: Appointments
events:
  emits:
    - AppointmentBooked
    - AppointmentCancelled

→ Every agent involved in this module only sees content scoped to Booking.

🔐 Agent and Skill Isolation by Context¶

Constraint	Purpose
`agentScope.context = Booking`	Prevents an agent from emitting or modifying unrelated modules
`skill.inputContext = Booking`	Ensures prompt injection, blueprint parsing, and artifact generation are scoped
`orchestrator.fsm.context = Booking`	Coordinates only agents and events in that boundary

✅ Enables secure, traceable, and parallel-safe automation.

🧩 Benefits of Context-Based Modularization¶

Benefit	Result
✅ Agent Independence	Agents don’t interfere with each other’s outputs
✅ Safe Parallelism	100s of agents can work simultaneously across contexts
✅ Blueprint-to-Module Clarity	Each blueprint file maps cleanly to a module path
✅ Scalable Orchestration	Coordinators operate per context with no global state
✅ Event-Driven Integration	Contexts evolve independently and collaborate safely

✅ Summary¶

In ConnectSoft, bounded contexts define modular units for generation, ownership, and orchestration
All blueprints, prompts, and agent executions are context-scoped
This enables safe, scalable, and composable automation across thousands of modules

🧼 Clean Layered Structure¶

In ConnectSoft, every module generated by agents follows a strict, opinionated Clean Architecture layout. This structure enforces separation of concerns, safe extensibility, and agent skill boundaries, while making automation traceable and repeatable.

“Clean layering isn’t just good practice — it’s how agents know what belongs where, and why.”

Each layer corresponds to a specific type of concern, a set of agent skills, and a set of blueprint declarations.

🧱 The Standard Clean Architecture Layers¶

Layer	Responsibility	Owned By
Domain	Business rules, aggregates, entities, value objects, domain events	`Domain Modeler Agent`, `Event-Driven Architect Agent`
Application	Use cases, command handlers, services, workflows	`Backend Developer Agent`, `QA Agent`
Infrastructure	External integrations (e.g., DB, messaging, APIs) via adapters	`Infrastructure Engineer Agent`, `Cloud Provisioner Agent`
Entry Points (API/UI)	Controllers, endpoints, gRPC services, UI views	`API Designer Agent`, `Frontend Developer Agent`
Tests	Unit, integration, behavior specs	`Test Generator Agent`, `QA Agent`

📘 Folder Structure Example¶

/BookingService/
  /Domain/
    Appointment.cs
    BookingAggregate.cs
    Events/
      AppointmentBooked.cs
  /Application/
    Handlers/
      BookAppointmentHandler.cs
    Services/
  /Infrastructure/
    Persistence/
      BookingRepository.cs
    Messaging/
      EventPublisher.cs
  /API/
    Controllers/
      AppointmentsController.cs
  /Tests/
    Features/
      BookAppointment.feature
    Unit/
  /Contracts/
    Events/
    OpenAPI/
  execution-metadata.json

✅ All ConnectSoft templates use this layout. Agents read/write only within their assigned layer.

🧠 Why This Matters for Agents¶

Prompts are injected with layer-specific input
Skills are mapped per layer (e.g., EmitDomainEvent → Domain, GenerateHandler → Application)
Coordinators know which agent to call based on blueprint layer
Validators enforce schema and artifact placement correctness
Reviewers can diff, approve, or reject changes by layer

🧩 Skill-to-Layer Alignment¶

Skill	Layer
`GenerateHandler`	Application
`EmitDomainEventContract`	Domain
`GenerateRepositoryAdapter`	Infrastructure
`GenerateOpenAPIContract`	API
`GenerateSpecFlowTest`	Tests

🔐 Layer Enforcement in Templates¶

Templates apply:

Layered path constraints (outputPath, layerTag)
Layer-specific linting rules (e.g., Application should not reference Infrastructure)
Agent-level access control (e.g., frontend-developer cannot modify /Domain)
Skill scoping (skillId: GenerateHandler, layer: Application)

🧪 Benefits of Layered Structure¶

Benefit	Outcome
✅ Agent modularity	Agents only operate in their assigned layer
✅ Traceability	Artifacts link back to skill + layer
✅ Validated generation	Validators can enforce layer contracts
✅ Diff isolation	Reviewers see changes per layer and purpose
✅ Safe evolution	You can regenerate one layer without touching others

✅ Summary¶

ConnectSoft enforces a strict layered architecture, enabling agents to generate code safely and deterministically
Layers map to skills, prompts, and agent scopes
This structure underpins traceability, validation, and agent collaboration

⚙️ Use Cases and Application Services¶

The Application Layer in ConnectSoft is where agents generate orchestrated, intent-driven workflows — typically as command or query handlers, application services, or invocable policies.

This layer is the “glue” between domain logic and infrastructure — and the execution core of modular agent output.

“The Application Layer is where blueprints become behavior — and agents become action.”

It represents user intent and business workflows without leaking infrastructure or persistence concerns.

🧠 Purpose of the Application Layer¶

Function	Description
Handle commands	Transform input into intent and invoke domain model behavior
Coordinate use cases	Glue together multiple domain operations under a single scenario
Call domain aggregates	Interact with domain via proper invariants and consistency
Emit domain events	Signal state transitions or policy triggers
Prepare output models	Return DTOs or responses for the outer layers (e.g., controllers, gRPC)

📘 Blueprint Example → Application Layer Mapping¶

useCase: Book Appointment
input:
  - petId: Guid
  - startTime: DateTime
  - duration: int
output: AppointmentBooked
layer: Application

→ Agent executes GenerateHandler, producing BookAppointmentHandler.cs under /Application/Handlers.

🧩 Agent Skills That Target Application Layer¶

Agent	Skills
`Backend Developer Agent`	`GenerateHandler`, `GenerateApplicationService`, `EmitCommandContract`
`Test Generator Agent`	`GenerateUnitTestForHandler`, `ScaffoldBDDFeature`
`QA Agent`	`ValidateApplicationFlow`
`Code Reviewer Agent`	`DetectAppLayerViolations`

📦 Standard Structure of a Handler¶

public class BookAppointmentHandler : IRequestHandler<BookAppointmentCommand, AppointmentResult>
{
    public async Task<AppointmentResult> Handle(BookAppointmentCommand command, CancellationToken ct)
    {
        var appointment = BookingAggregate.Book(command.PetId, command.StartTime, command.Duration);
        await _repository.SaveAsync(appointment);
        _eventPublisher.Publish(new AppointmentBooked(...));
        return new AppointmentResult(...);
    }
}

✅ Generated by backend-developer agent based on blueprint + domain model structure.

🧠 Why Application Layer Is Agent-Friendly¶

Inputs/outputs are well-typed and declarative
Each use case maps to one skill execution
Prompt can be deterministically constructed from blueprint section
Validators can confirm that:
- No infrastructure leakage
- Events are correctly raised
- Domain is invoked through proper aggregate root
Skill outputs are idempotent and testable

🧪 Application-Level Testing¶

Test generators use this layer to:

Scaffold SpecFlow/BDD scenarios
Generate unit tests with mocks for domain/services
Attach tests to the same traceId as handler generation
Validate alignment between use case input and test flow

🔁 Regeneration Scenarios¶

If the blueprint changes:

✅ Only this handler is regenerated
❌ Domain, infra, or contracts remain untouched
✅ Tests are updated or flagged if drift is detected

→ Keeps regeneration localized and safe.

✅ Summary¶

The Application Layer is the execution point for agent-generated workflows
It translates blueprint-defined use cases into handlers and services
Clean layering and structured prompts allow for safe, deterministic, and traceable code generation

🧱 Aggregates and Domain Events¶

At the core of ConnectSoft’s domain modeling lies the aggregate — a consistency boundary for core business rules — and the domain event, which acts as a signal of meaningful state change.

These constructs are not just important for clean design — they are essential to agent-driven generation, modular orchestration, and event-based collaboration across contexts.

“Aggregates define what agents protect. Domain events define what agents trigger.”

🧩 What Is an Aggregate?¶

An aggregate is:

A consistency boundary around one or more entities
The only place in the domain where invariants are enforced
The source of domain events
Scoped to a bounded context, versioned, and owned by the domain model

Example:

public class BookingAggregate : AggregateRoot
{
    public Appointment BookAppointment(PetId petId, DateTime startTime, int duration)
    {
        // domain rules
        var appointment = new Appointment(...);
        AddDomainEvent(new AppointmentBooked(...));
        return appointment;
    }
}

📘 Domain Events: Meaningful State Transitions¶

Domain events describe facts in past tense:

AppointmentBooked
InvoiceGenerated
UserRegistered

They are emitted by aggregates and consumed by:

🧠 Other domain models
⚙️ Coordinators and agents
🧪 Test validators
🚀 Pipelines and deployment triggers

📦 Blueprint → Aggregate → Event Flow¶

aggregate: Booking
command: BookAppointment
emitsEvent: AppointmentBooked

→ Used by Domain Modeler Agent to create:

BookingAggregate.cs
Appointment.cs
AppointmentBooked.cs (domain event)

🧠 Agent Roles in Domain Modeling¶

Agent	Skills
`Domain Modeler Agent`	`GenerateAggregate`, `EmitDomainEvent`, `DefineEntityStructure`
`Backend Developer Agent`	`EmitCommandInvoker`, `RaiseEventFromAggregate`
`Event-Driven Architect Agent`	`MapEventContracts`, `AttachIntegrationPolicy`

🧪 Why Aggregates Matter for Agents¶

They centralize business rules, allowing safe code generation
Events generated are well-scoped signals, usable across flows
Output of one agent (handler) becomes input trigger for another
Validators can confirm that:
- Domain rules exist in one place
- All commands result in events
- Events follow contract structure

🔄 Event Emission → Event-Driven Automation¶

When a domain event is emitted:

Orchestrator receives AppointmentBooked
Notification Agent, Analytics Agent, or QA Agent are triggered
CI pipeline may generate release if event == ReleaseReady
Other services consume event via contracts and anti-corruption layers

→ This powers autonomous module collaboration.

🔐 Aggregate Rules in Templates¶

One aggregate per module
Domain events versioned and namespaced
Agents never emit events without passing through an aggregate
All aggregates include AddDomainEvent() utility method
Domain events are scaffolded with schemas + observability metadata

✅ Summary¶

Aggregates protect business logic — domain events expose business state changes
ConnectSoft agents use these constructs to generate, trigger, and orchestrate flows
They enable safe, autonomous collaboration and enforce domain boundaries across modules

🗃️ Repositories and Persistence Models¶

In ConnectSoft, persistence logic is treated as an infrastructure concern, separated entirely from the domain and application layers. This separation is enforced via repositories, which agents generate based on domain aggregates and context-aware blueprints.

“Agents don’t care about where data lives — only how it’s accessed and validated via contracts.”

Repositories give agents a stable abstraction to generate testable, swappable, and tenant-aware storage logic without coupling the core domain to any specific database, ORM, or transport layer.

🧠 Strategic Role of Repositories¶

Purpose	Benefit
Abstract persistence	Keeps domain and app layers persistence-agnostic
Enable mocking	Agents generate test doubles and in-memory implementations
Support multitenancy	Tenant filtering can be enforced at adapter layer
Prepare for swapability	Easily replace NHibernate, MongoDB, or EF adapters
Align with Clean layering	Ensures dependency inversion is respected in generated code

🧩 Blueprint → Repository Mapping¶

aggregate: Booking
repository:
  interface: IBookingRepository
  entity: Appointment
  persistence: nhibernate
  multiTenant: true

→ Triggers:

IBookingRepository.cs (App layer)
BookingRepository.cs (Infra adapter)
NHibernate mappings (if required)
Tenant scoping logic

🧱 Repository Layered Structure¶

Layer	Artifact	Generator Agent
Application	`IBookingRepository`	`Backend Developer Agent`
Infrastructure	`BookingRepository : IBookingRepository`	`Infrastructure Engineer Agent`
Tests	`InMemoryBookingRepository`	`Test Generator Agent`

✅ These are scoped per module and traceable via agent metadata.

🧠 Clean Repository Contracts¶

public interface IBookingRepository
{
    Task<Appointment?> GetByIdAsync(Guid id);
    Task SaveAsync(Appointment appointment);
}

✅ Domain never references infrastructure — only the interface.

🧪 Repository Testability¶

Generated repositories support:

In-memory variants for unit testing
Fake adapters with assertion hooks
Integration test stubs with seed data
Tracing of queries for validation and observability

🔁 Regeneration & Agent Workflow¶

When aggregate or blueprint changes:

✅ Repository interface is regenerated
✅ Adapter class is diffed or re-emitted
✅ Tests regenerate if behavior changes
❌ Domain layer remains untouched unless event structure changes

🔐 Repository Constraints in Templates¶

Naming convention: <Aggregate>Repository.cs
All adapters respect tenantId injection pattern
Cross-context access prohibited (e.g., Booking repo in Billing context)
Versioned schema/contract overlays supported (e.g., v1, v2)
ORM-specific generation via template flag (useNHibernate, useMongo, etc.)

📘 Optional: Specification Pattern Support¶

If enabled, agents can also generate query objects and specifications:

public class AppointmentsByDateSpec : ISpecification<Appointment>
{
    public DateTime Date { get; }

    public Expression<Func<Appointment, bool>> ToExpression() =>
        x => x.StartTime.Date == Date;
}

→ Covered more deeply in Specifications and Queries section.

✅ Summary¶

Repositories give agents a clean contract to read/write data across contexts
The domain layer stays pure — agents handle persistence as a separate, swappable concern
This pattern enables testability, multi-ORM support, and infrastructure modularity

🧬 Entity Modeling for Agents¶

ConnectSoft agents don’t just scaffold code — they model domain realities. Using structured prompts and blueprint data, agents generate entities, value objects, and domain rules that reflect the ubiquitous language of the bounded context.

“Entity modeling is where the blueprint becomes behavior — and the language becomes structure.”

This modeling phase happens primarily in the Domain Layer, led by the Domain Modeler Agent and validated by orchestration flows and contract tests.

🧠 What Is an Entity?¶

An entity:

Has an identity (Id)
Represents a business concept with behavior
Evolves over time
Is compared by identity (not value)
Lives inside an aggregate or root

Example:

public class Appointment
{
    public Guid Id { get; init; }
    public DateTime StartTime { get; private set; }
    public PetId PetId { get; private set; }

    public void Reschedule(DateTime newStartTime)
    {
        StartTime = newStartTime;
    }
}

📘 Value Object Example¶

public record PetName(string First, string Last);

✅ No identity — compared by value, not reference. Agents generate value objects when isValue: true is declared.

🧩 Blueprint → Entity Mapping¶

entities:
  - name: Appointment
    fields:
      - name: Id
        type: Guid
      - name: StartTime
        type: DateTime
      - name: PetId
        type: PetId
    behaviors:
      - Reschedule
    aggregate: Booking
    isValue: false

→ Used by Domain Modeler Agent to generate:

Appointment.cs (Entity)
PetId.cs (Value Object)
Reschedule() method
Blueprint-derived constructor

🤖 Agent-Driven Modeling Process¶

Agent reads blueprint or prompt containing domain vocabulary
Matches terms to modeling templates (e.g., entity, value object, aggregate)
Validates field types and modifiers
Injects guard clauses or invariant checks
Emits artifacts with metadata (traceId, skillId, contextId)
Validates output via structural and semantic checks

🧩 Skills for Domain Modeling¶

Agent	Skills
`Domain Modeler Agent`	`GenerateEntity`, `GenerateValueObject`, `InjectInvariants`, `AttachToAggregate`
`Ubiquitous Language Agent`	`ExtractConcepts`, `MapDomainTermsToModels`
`Backend Developer Agent`	`UseEntityInHandler`, `MapDTOs`

🧪 Validation and Observability¶

Each generated entity:

Is schema-validated against the blueprint
Includes annotations for traceability (source skill, context, field origin)
Is verified by structural rules (e.g., “all entities must have Id”)
Is unit tested via agent-generated specs if behaviors exist

🔄 Regeneration Triggers¶

Regeneration occurs when:

Blueprint fields or types change
Aggregates evolve (new domain rules)
Entity relationships are updated
Value object flags change (e.g., isValue: false → true)

✅ Only affected models are regenerated — agents work at fine-grained modularity.

📊 Studio Visualization¶

Studio shows:

Entity structure and hierarchy per context
Relationships to aggregates and repositories
Cross-reference to DTOs, events, and test cases
Change history and regeneration diffs

✅ Summary¶

ConnectSoft agents model domain entities and value objects based on blueprint input and ubiquitous language
The result is clean, testable, behavior-rich models that reflect business intent
Modeling is traceable, auditable, and safely regenerable

🔍 Specifications and Queries¶

In ConnectSoft, complex read-side logic is not hardcoded into repositories or scattered across handlers. Instead, the platform supports clean, reusable specifications and query models, which agents can generate, reuse, and validate.

“Specifications let agents express ‘what to fetch’ without knowing ‘how to fetch it’.”

This pattern enables scalable, testable query logic — fully compatible with Clean Architecture and DDD principles — and allows both command and query flows to be agent-driven.

🧠 What Is a Specification?¶

A Specification is:

A reusable object that expresses a filter or business rule
Independent of persistence technology
Composed of predicates (usually LINQ expressions)
Often used for queries, validations, and guards

Example:

public class AppointmentsByDateSpec : ISpecification<Appointment>
{
    public DateTime Date { get; }

    public Expression<Func<Appointment, bool>> ToExpression() =>
        x => x.StartTime.Date == Date;
}

🧩 Blueprint to Specification Mapping¶

queries:
  - name: AppointmentsByDate
    entity: Appointment
    filter:
      - field: StartTime
        condition: date = Today
    output: List<AppointmentDto>
    layer: Application

→ Used by agents to generate:

AppointmentsByDateSpec.cs
GetAppointmentsByDateQuery.cs
Optional AppointmentsByDateHandler.cs if CQRS is used

🧰 Agent Skills for Query Logic¶

Agent	Skills
`Backend Developer Agent`	`GenerateQueryHandler`, `AttachSpecification`, `GenerateDTO`
`Domain Modeler Agent`	`EmitSpecification`
`QA Agent`	`ValidateQueryOutput`, `GenerateQueryTest`

🧩 Specification Composition¶

Agents can compose logic using reusable blocks:

var spec = new AppointmentsByDateSpec(DateTime.Today)
    .And(new PetTypeSpec("Dog"))
    .Or(new StatusSpec("Pending"));

✅ Supports complex logic using a modular, testable model.

📘 Query Handlers Example (CQRS)¶

public class GetAppointmentsByDateHandler : IRequestHandler<GetAppointmentsByDateQuery, List<AppointmentDto>>
{
    private readonly IAppointmentRepository _repo;

    public async Task<List<AppointmentDto>> Handle(GetAppointmentsByDateQuery query, CancellationToken ct)
    {
        var spec = new AppointmentsByDateSpec(query.Date);
        var results = await _repo.ListAsync(spec);
        return results.MapToDto();
    }
}

✅ Cleanly separates logic: query → spec → projection.

🧪 Agent-Generated Query Tests¶

The Test Generator Agent can:

Generate test data for query specs
Verify correctness of filtering logic
Mock repositories and confirm results
Create negative test cases (e.g., no matches)

🔄 Regeneration Triggers¶

Specifications and queries are regenerated when:

Blueprint declares new query patterns
Entity model changes affect filter logic
DTO projections are updated
Repository interface is modified

📦 Benefits of Specifications in Agent Workflows¶

Benefit	Outcome
✅ Reusable logic	Shared across queries, validators, and test setups
✅ Layered separation	Clean architecture compliance without leaks
✅ Prompt-based generation	Easy to instruct agents via blueprint or prompt
✅ Testable and composable	Specification = pure function = unit testable

✅ Summary¶

Specifications enable agents to express read logic cleanly and safely
They align with Clean Architecture and enable CQRS-compatible workflows
Agent-generated specs, queries, and tests are modular, reusable, and maintainable

📣 Domain Events as Signals¶

In ConnectSoft, domain events are not just internal notifications — they are the primary signals that drive orchestration, downstream agent activation, and cross-context automation.

“A domain event is a fact — one that triggers flows, unlocks dependencies, and enables collaboration.”

These events originate from aggregates, reflect meaningful state changes, and are used to activate agents, trigger CI/CD pipelines, update documentation, or emit integration artifacts.

🧠 Strategic Role of Domain Events¶

Purpose	Impact
✅ Signal state transitions	Tell the system: “Something important just happened”
✅ Decouple workflows	Producers and consumers don’t need to know about each other
✅ Enable orchestration	Coordinators react to domain events via FSM transitions
✅ Trigger agents	Events activate new skills, validation flows, and downstream steps
✅ Emit contracts	Events can be mapped to external schemas or pub/sub endpoints

📘 Example: Aggregate → Event → Agent¶

public class BookingAggregate
{
    public Appointment Book(...) {
        ...
        AddDomainEvent(new AppointmentBooked(...));
        return appointment;
    }
}

→ This emits:

event: AppointmentBooked
context: Booking
traceId: abc123
source: BookingAggregate

→ Which triggers:

Notification Agent
Analytics Agent
Deployment Orchestrator
Studio pipeline trace

🔁 Event Flow Pattern¶

sequenceDiagram
  participant BookingAggregate
  participant EventBus
  participant QA Agent
  participant DevOps Coordinator

  BookingAggregate->>EventBus: Emit AppointmentBooked
  EventBus->>QA Agent: Activate test validation
  EventBus->>DevOps Coordinator: Transition to ReadyForRelease

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

✅ No hardcoding, only event-contract-driven automation.

📦 Blueprint → Event Mapping¶

events:
  emits:
    - AppointmentBooked.v1
    - AppointmentCancelled.v1
  consumes:
    - UserRegistered.v1

Each emitted event is versioned, documented, and assigned a schema (JSON or C# contract).

🧩 Agent Skills for Event Handling¶

Agent	Skills
`Domain Modeler Agent`	`EmitDomainEvent`, `GenerateEventContract`
`Backend Developer Agent`	`AttachEventToHandler`, `RouteCommandToAggregate`
`Event-Driven Architect Agent`	`MapCrossContextFlows`, `DesignEventContracts`
`QA Agent`	`VerifyEventEmission`
`Documentation Writer Agent`	`IncludeEventInAPIDocs`

🔐 Event Contract Enforcement¶

All events must have a contract schema (*.v1.json)
Emitted events are validated at runtime
Agents must declare emitted events in metadata
Studio visualizes event topology across modules
Contracts are versioned (v1, v2, vN) with compatibility checks

🧠 Advanced Use: Orchestration Triggers¶

Domain events trigger state transitions:

state: awaitingTest
on:
  - event: TestSuitePassed
    transitionTo: readyForRelease

Or trigger agent workflows:

onEvent: AppointmentBooked
invoke:
  - NotifyClientAgent
  - UpdateCalendarAgent

✅ Summary¶

Domain events are the primary signals for automation, agent activation, and inter-context flow
Every meaningful change in ConnectSoft produces an event that feeds into orchestration, pipelines, and observability
Domain events are modeled, versioned, and enforced by contracts — with full traceability

🧭 Strategic Blueprint Mapping¶

In ConnectSoft, blueprints are the machine-readable source of truth for what needs to be built, why, and how. They map directly to Clean Architecture layers and DDD concepts, enabling agents to generate code, contracts, and flows with precision and safety.

“Blueprints are not specs — they are execution plans aligned with clean layering and bounded contexts.”

This mapping is what allows agents to function autonomously: a well-structured blueprint eliminates ambiguity and allows precise targeting of skills and outputs.

📘 Blueprint = Modular Execution Contract¶

Blueprints include structured declarations that guide agent behavior:

module: BookingService
context: Booking
aggregate: Booking
commands:
  - BookAppointment
  - CancelAppointment
events:
  emits:
    - AppointmentBooked
    - AppointmentCancelled
entities:
  - Appointment
queries:
  - AppointmentsByDate
infrastructure:
  persistence: nhibernate
  pubsub: azure-service-bus

Each section maps to:

A layer in Clean Architecture
A set of agents
One or more output artifacts

🧱 Blueprint-to-Layer Mapping¶

Blueprint Section	Clean Architecture Layer	Generated By
`commands`	Application	`Backend Developer Agent`
`aggregate`, `entities`	Domain	`Domain Modeler Agent`
`events`	Domain (+ Contracts)	`Event-Driven Architect Agent`
`queries`	Application	`Backend Developer Agent`
`infrastructure.persistence`	Infrastructure	`Infrastructure Engineer Agent`
`api.contracts`	Entry Point	`API Designer Agent`
`tests`	Test Layer	`Test Generator Agent`

🧩 Agent Workflow Driven by Blueprint Sections¶

BlueprintCreated → triggers agent chain
Each agent reads the section(s) it’s scoped to
Outputs are saved under layer-aligned folders
Coordinators verify all required blueprint sections are implemented and validated

🔁 Modular Generation Lifecycle¶

graph TD
  Blueprint --> Domain
  Blueprint --> Application
  Blueprint --> Infrastructure
  Blueprint --> Contracts
  Blueprint --> Tests

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

→ This modularity allows regeneration of one layer at a time, based on partial blueprint updates.

🧠 Multi-Agent Execution by Section¶

Section	Activated Agents
`commands`	`Backend Developer Agent`, `QA Agent`
`aggregate`	`Domain Modeler Agent`, `Event-Driven Architect Agent`
`infrastructure`	`Infrastructure Engineer Agent`, `Cloud Provisioner Agent`
`tests`	`Test Generator Agent`, `QA Agent`

Each agent uses structured prompt templates mapped to its blueprint domain.

📊 Traceability & Validation¶

Blueprint mapping supports:

Skill-level validation (e.g., GenerateHandler must match command section)
Missing section detection (e.g., handler exists but event not defined)
Studio trace graphs linking blueprint source → agent → output artifact
Retry/resume per section during orchestrated flows

✅ Summary¶

Blueprints are modular execution plans, not freeform documents
Each section maps to DDD concepts and Clean Architecture layers
This structured mapping enables safe, partial, and traceable generation across agents and flows

🧱 Code Generation by Layer¶

In ConnectSoft, agents don’t emit code blindly — they generate artifacts layer-by-layer, respecting Clean Architecture boundaries and DDD ownership. Each layer has a defined purpose, structure, and a set of agent skills responsible for its outputs.

“Layered generation enforces modularity, separation of concerns, and safe parallel automation.”

This architectural discipline ensures that code is generated in a predictable, validated, and traceable way — with each layer supporting composability, testability, and safe regeneration.

🧱 Layer Responsibilities Recap¶

Layer	Purpose
Domain	Core business logic (aggregates, entities, value objects, domain events)
Application	Use case orchestration, command/query handlers, DTO mappings
Infrastructure	Persistence, messaging, integrations (via adapters)
Entry Points	HTTP APIs, gRPC services, controllers, UI ports
Tests	Unit, integration, feature, and specification tests

🤖 Agent Code Generation by Layer¶

Layer	Agent	Skills
Domain	`Domain Modeler Agent`	`GenerateAggregate`, `GenerateEntity`, `EmitDomainEvent`
Application	`Backend Developer Agent`	`GenerateHandler`, `EmitCommandContract`, `GenerateApplicationService`
Infrastructure	`Infrastructure Engineer Agent`	`GenerateRepositoryAdapter`, `ConfigureDbContext`, `EmitQueuePublisher`
Entry Points	`API Designer Agent`, `Frontend Developer Agent`	`GenerateOpenApiContract`, `ScaffoldController`, `EmitUIAdapter`
Tests	`Test Generator Agent`, `QA Agent`	`GenerateUnitTest`, `GenerateSpecFlowFeature`, `CreateMockRepository`

✅ Each skill is scoped to a layer, blueprint section, and trace context.

🧩 Sample Generation Sequence¶

flowchart TD
  Blueprint --> Domain
  Domain --> Application
  Application --> Infrastructure
  Application --> EntryPoints
  All --> Tests

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

→ Domain is generated first → Application builds on domain contracts → Infrastructure adapters scaffold for domain interfaces → Entry points expose App layer → Tests wrap around all others

📁 Folder Output Structure¶

/modules/
  Booking/
    /Domain/
    /Application/
    /Infrastructure/
    /API/
    /Tests/
    execution-metadata.json

→ All artifacts are stored by layer with traceable metadata, versioning, and agent linkage.

🔁 Regeneration and Safety¶

If a blueprint or prompt change affects:

✅ Only Application → regenerate handler, not domain
✅ Only Infrastructure → regenerate adapter, not logic
✅ A shared model → agents update layer-specific projections or adapters
✅ Test drift → regenerate tests without impacting implementation

→ Partial regeneration is safe and isolated.

🧪 Layer-Aware Validation¶

Validators enforce:

Application must only depend on Domain
Infrastructure must not reference Domain directly
Tests must use mocks or contracts
Event names must match domain event definitions
Output folders must align to declared layer in agent output metadata

🧠 Benefits of Layered Code Generation¶

Benefit	Description
✅ Separation of concerns	Prevents cross-layer leakage in AI output
✅ Skill modularity	Skills stay focused and reusable
✅ Safe recomposition	Agents can regenerate or reflow just one layer
✅ Observability	Each artifact is linked to agent, skill, and layer
✅ Governance	Reviewers can focus on one layer per MR or PR phase

✅ Summary¶

Each Clean Architecture layer in ConnectSoft is mapped to agent skills and blueprint sections
Code is generated in phases, with layer-specific outputs, validation, and traceability
This ensures high-quality, composable automation with clear separation of concerns

🧰 Template Constraints and Conventions¶

In ConnectSoft, code is generated from opinionated templates that enforce architectural correctness, layering discipline, naming standards, and skill-to-folder alignment. These constraints ensure that agents consistently produce clean, valid, and maintainable code — no matter how many modules are generated.

“Templates are not scaffolds — they’re guardrails for intelligent automation.”

This cycle describes how templates encode ConnectSoft’s Clean Architecture conventions and how they are enforced during code generation.

🧠 Why Constraints Matter for AI Agents¶

Without constraints:

Agent output drifts from best practices
Layer boundaries are crossed
Test coverage becomes inconsistent
Naming, file paths, and contracts are unpredictable

With constraints:

Every artifact is where it belongs
Agents only emit valid, buildable, and auditable code
Errors are caught at generation time, not during integration

📦 Layer-Based Template Enforcement¶

Layer	Enforced Constraints
Domain	No infrastructure references; only aggregates, entities, value objects, and domain events allowed
Application	Must depend only on Domain; handlers must raise domain events; commands must match contracts
Infrastructure	Only adapters and service wiring; no business logic or domain rules
Entry Points	Controller actions must call only Application services; no repository access allowed
Tests	Must use mocks, stubs, or generated fixtures; each handler must have coverage if testing is enabled

🧩 Naming & File Path Conventions¶

All templates enforce standard naming and file placement:

Artifact	Convention
Aggregate	`Domain/Aggregates/{Name}Aggregate.cs`
Command Handler	`Application/Handlers/{CommandName}Handler.cs`
Repository Interface	`Application/Contracts/I{Name}Repository.cs`
Repository Adapter	`Infrastructure/Persistence/{Name}Repository.cs`
Domain Event	`Domain/Events/{EventName}.cs`
Test File	`Tests/Features/{ScenarioName}.feature`

✅ Ensures predictability and traceability across thousands of modules.

🧪 Template-Driven Validation Hooks¶

Each template registers post-generation validators:

✅ Structure validator (expected folders and file names)
✅ Dependency validator (no illegal references between layers)
✅ Blueprint-field match validator (command names, entity fields)
✅ Prompt input coverage validator (ensures skill output reflects all inputs)
✅ Linter and formatting rules (naming conventions, spacing, casing)

🧠 Example: Enforced Handler Output¶

public class BookAppointmentHandler : IRequestHandler<BookAppointmentCommand, AppointmentDto>
{
    private readonly IBookingRepository _repo;
    private readonly IEventPublisher _eventPublisher;

    public async Task<AppointmentDto> Handle(BookAppointmentCommand command, CancellationToken ct)
    {
        var booking = BookingAggregate.Book(...);
        await _repo.SaveAsync(booking);
        _eventPublisher.Publish(new AppointmentBooked(...));
        return booking.ToDto();
    }
}

✅ Matches layer responsibilities ✅ References domain, not infrastructure ✅ Emits event ✅ Returns DTO, not entity

🔐 Prompt + Template Coupling¶

Prompts are parameterized and tied to templates, not freeform:

skill: GenerateHandler
template: handler/app-layer/v1
input:
  command: BookAppointment
  aggregate: Booking
  outputEvent: AppointmentBooked

→ Ensures that agent output always aligns with the factory’s architecture model.

🧱 Build-Phase Enforcement¶

CI/CD pipelines and agents validate that:

Output files match expected location & naming
Artifacts are registered in execution-metadata.json
Code builds successfully before publishing
Code coverage thresholds are met for testable layers

✅ Summary¶

Templates in ConnectSoft enforce Clean Architecture alignment by design
Every layer has guardrails, validators, and naming rules baked into generation logic
This ensures that AI agents produce predictable, traceable, and scalable artifacts

🏗️ Infrastructure Independence¶

In ConnectSoft, infrastructure is treated as a secondary concern — essential for execution but never allowed to pollute the core domain. This aligns with Clean Architecture principles and enables AI agents to swap, adapt, or regenerate infrastructure code without touching application or domain logic.

“Infrastructure is where implementation lives — but never where decisions start.”

This principle gives ConnectSoft the ability to generate, validate, and replace persistence, messaging, and external integrations dynamically and modularly.

🧠 Why Infrastructure Must Be Independent¶

Risk if Coupled	Strategic Consequence
Infrastructure bleeds into domain	Business logic becomes fragile and non-portable
Application knows about DB or queues	Tests become slow, brittle, and complex
Regeneration of infra breaks core logic	Increases agent risk and reduces automation safety
Multi-tenant layering is compromised	Security and isolation violations occur

✅ ConnectSoft treats all infrastructure as pluggable adapters governed by interfaces.

🧩 Clean Structure of Infra Layer¶

Component	Purpose
Adapters	Implement `IRepository`, `IQueuePublisher`, `IExternalServiceClient`
Factories	Wire dependencies for injection
Mappings	Define schema for NHibernate, MongoDB, Dapper, etc.
Transport Modules	Handle communication with queues, REST APIs, services
Tenant Guards	Enforce per-tenant scoping at adapter boundaries

📘 Blueprint → Infra Template Mapping¶

infrastructure:
  persistence: nhibernate
  pubsub: azure-service-bus
  adapters:
    - AppointmentPublisher
    - BookingRepository

→ Triggers:

BookingRepository.cs
AppointmentPublisher.cs
NhBookingMapping.hbm.xml or Bicep modules
QueueBindings.json for messaging configuration

🤖 Agent-Driven Infrastructure Generation¶

Agent	Skills
`Infrastructure Engineer Agent`	`GenerateRepositoryAdapter`, `EmitDbMapping`, `GenerateServiceClient`
`Cloud Provisioner Agent`	`GenerateBicepModule`, `InjectInfraSecrets`
`DevOps Engineer Agent`	`GenerateTransportBindings`, `ConfigureConnectionStrings`

🔁 Infrastructure Swap Patterns¶

If blueprint or tenant config changes:

✅ Swap NHibernate → MongoDb → regenerate adapter only
✅ Replace ServiceBus with EventGrid → generate new transport binding
✅ Add TenantFilter to repository → only adapter is touched

→ Domain and App layers are never modified.

🔒 Enforcement Rules¶

Templates and validators ensure:

Infra code cannot reference domain or application types
Adapter files must follow Infrastructure/Adapters/* convention
Connection strings and secrets are injected via config only
Adapters include built-in tenantId or context-scoping guards
All outbound communication is traceable by artifact and event contract

🧪 Infra Layer Testability¶

Agents generate:

In-memory adapters for unit tests
Mocks and fakes via Test Generator Agent
Integration tests with test containers or stubs
Configuration diff reports (e.g., infra-config-changes.json)

✅ Summary¶

Infrastructure in ConnectSoft is modular, swappable, and strictly separated from core logic
AI agents treat infrastructure as adapter outputs, never as business dependencies
This principle enables safe regeneration, tenant isolation, and portability across cloud platforms

🧪 Domain-Led Testing¶

In ConnectSoft, testing is not a last step — it’s a first-class citizen of the generation pipeline. Tests are generated based on domain behavior, blueprint-defined use cases, and expected outputs. This results in executable specifications that validate domain logic, use case flows, and system invariants — across all layers.

“If a use case exists in the blueprint, it has a test. No exceptions.”

The Test Generator Agent and QA Agent collaborate to ensure that every command, event, and scenario is validated through clean, layered, and traceable tests.

🧠 Why Domain-Led Testing?¶

Goal	Enabled By
✅ Verify domain behavior	Aggregates and entities tested via core invariants
✅ Validate use cases	Application services and handlers tested against input/output
✅ Ensure traceability	Test scenarios are linked to blueprint items and agent executions
✅ Support CI/CD automation	Generated tests are part of orchestrated flows and code contracts

📘 Blueprint → Test Flow Mapping¶

useCases:
  - name: BookAppointment
    input:
      - petId: Guid
      - startTime: DateTime
    expectedEvent: AppointmentBooked
    test:
      name: "Book appointment successfully"
      type: BDD
      validate: outputEvent

→ This triggers generation of:

BookAppointment.feature (SpecFlow)
BookAppointmentHandlerTests.cs (unit test)
BookingAggregateTests.cs (aggregate test)
AppointmentsByDateSpecTests.cs (spec validation)

🧩 Agent Skills for Testing¶

Agent	Skills
`Test Generator Agent`	`GenerateSpecFlowTest`, `GenerateUnitTestForHandler`, `GenerateAggregateTest`
`QA Agent`	`ValidateTestCoverage`, `EmitTestContractResults`, `FlagMissingTests`
`Bug Investigator Agent`	`GenerateReproScenario`, `InjectEdgeCaseTest`

📦 Types of Tests Generated¶

Test Type	Target
SpecFlow Features	User stories and scenarios from blueprints
Unit Tests	Handlers, aggregates, services
Integration Tests	Repositories, pub/sub, external API clients
Event Flow Assertions	Domain events emitted and consumed
Edge Case & Regression Tests	Based on feedback or trace diffs

🧪 Example: Generated Unit Test¶

[Fact]
public async Task BookAppointmentHandler_ShouldEmit_AppointmentBooked()
{
    var command = new BookAppointmentCommand(...);
    var handler = new BookAppointmentHandler(...);
    var result = await handler.Handle(command, default);

    _eventPublisherMock.ShouldHavePublished<AppointmentBooked>();
    result.ShouldNotBeNull();
}

✅ Generated alongside the handler, named according to conventions, and fully traceable.

🧠 Observability and Validation¶

Each test artifact includes:

traceId, agentId, skillId, and blueprintSection
Links to the use case, event, and entity it validates
Code coverage tracked and surfaced in Studio
Diff viewer for test regeneration with semantic output comparison

🔁 Test Regeneration Strategy¶

Trigger	Result
New use case in blueprint	New SpecFlow + unit test
Changed output contract	Affected test cases regenerated
Refactored aggregate	Only aggregate test regenerated
Failed validation	Agent-triggered rerun + feedback captured

📊 CI Integration¶

Generated tests:

Are compiled, executed, and validated in CI/CD pipelines
Emit TestSuiteGenerated, TestSuitePassed, or TestSuiteFailed events
Block release transitions if test coverage or pass rate is below threshold
Are automatically tagged and traced per orchestrated module build

✅ Summary¶

Domain-led testing ensures that every AI-generated flow is verifiable, executable, and traceable
Tests are linked to blueprints, agents, and prompts — and are generated alongside core logic
This enables safe automation, quality assurance, and confidence in every module

🏢 Multi-Tenant Domain Isolation¶

ConnectSoft is a multi-tenant SaaS factory by design — and Domain-Driven Design (DDD) with Clean Architecture plays a critical role in ensuring that each tenant’s data, logic, and configuration remain isolated.

“In ConnectSoft, tenants don’t just use modules — they receive isolated, domain-aligned blueprints.”

Domain isolation enables tenant-specific behavior without code duplication, while maintaining architectural purity, automation safety, and observability.

🧠 Isolation by Design, Not by Patch¶

Isolation Concern	Handled By
Data	Tenant-scoped repositories, per-tenant DB schemas
Logic	Edition-specific blueprint overlays
Configuration	Scoped infrastructure adapters (e.g., per-tenant queues, APIs)
Events	Tenant-tagged emissions and scoped routing
Agent Execution	Per-tenant context injected into prompt, skill, and coordinator

📘 Blueprint → Tenant Configuration Mapping¶

tenantId: vetclinic001
module: BookingService
edition: premium
overrides:
  - CancelAppointment enabled
  - SMSReminders enabled
context: Booking

→ Triggers:

Enriched prompt and blueprint generation
Edition-specific handler logic
Infrastructure isolation for outbound integrations
Tenant-specific testing and trace context

🧩 Tenant Isolation Enforcement in Clean Layers¶

Layer	Isolation Strategy
Domain	No tenant logic here — pure rules, reusable across tenants
Application	Conditional logic injected based on edition features
Infrastructure	Repositories and clients scoped via tenant ID injection
Entry Points	Auth & routing filtered by tenant claims
Tests	Test scenarios executed per tenant blueprint with injected data

🔐 Enforcement via Agent Metadata and Templates¶

Each agent execution is tied to a tenantId and projectId
Prompts include tenant and edition context
Generated files are tagged and stored in tenant-specific directories
Infrastructure agents create isolated config files and secrets (e.g., Azure Key Vault per tenant)
Studio guards regeneration/editing by tenant scope permissions

🤖 Agent Skills Supporting Tenant Isolation¶

Agent	Skills
`Backend Developer Agent`	`InjectEditionLogic`, `MapFeatureToggles`
`Cloud Provisioner Agent`	`GenerateTenantScopedBicep`
`Infrastructure Engineer Agent`	`ConfigureTenantDB`, `GeneratePerTenantQueueBindings`
`QA Agent`	`RunTenantSpecificTests`, `ValidateEditionCoverage`

📦 Folder Structure Example¶

/tenants/
  vetclinic001/
    /BookingService/
      /Domain/
      /Application/
      /Infrastructure/
      /Tests/
      booking-service.execution-metadata.json

→ Keeps generation, deployment, and traceability scoped per tenant.

📊 Observability Per Tenant¶

Studio and telemetry dashboards show:

Module status per tenant
Test coverage and release metrics scoped by tenantId
Agent success/failure rates by tenant
Event flow visualization for per-tenant orchestration

✅ Summary¶

Multi-tenancy is achieved via clean isolation, tenant-scoped blueprints, and layered enforcement
Domain logic remains pure, while tenant-specific adaptations happen in the Application and Infrastructure layers
This enables safe, scalable, and traceable tenant-specific generation without code duplication

🔀 CQRS and Event Sourcing Support¶

ConnectSoft supports Command Query Responsibility Segregation (CQRS) and Event Sourcing as optional architectural patterns — applied strategically when the domain, blueprint, or scalability requirements justify it.

“CQRS and Event Sourcing are not default — they’re agent-triggered based on blueprint intent.”

These patterns allow the platform to split read and write concerns, persist source-of-truth events, and automatically generate projections, all while staying aligned with Clean Architecture and DDD boundaries.

🧠 When to Use CQRS¶

Trigger	Rationale
High read/write disparity	Optimize read projections independently
Complex domain events	Capture immutable history per aggregate
Audit/trace required	Persist events instead of just state
Blueprint explicitly defines `cqrs: true`	Enforce command/query split and projection generation

📘 Blueprint Example Enabling CQRS¶

cqrs: true
aggregate: Booking
commands:
  - BookAppointment
  - CancelAppointment
queries:
  - AppointmentsByDate
eventSourcing: true

→ Triggers agents to:

Generate event-sourced aggregate methods
Store AppointmentBooked, AppointmentCancelled events
Emit projections (AppointmentsReadModel)
Use handlers like IRequestHandler<Command> and IRequestHandler<Query> separately

🧩 Code Artifacts per Pattern¶

Component	Generated File
Command Handler	`BookAppointmentHandler.cs`
Event	`AppointmentBooked.cs`
Event Store Adapter	`EventStoreRepository.cs`
Projection	`AppointmentsReadModel.cs`
Query Handler	`GetAppointmentsByDateHandler.cs`

✅ Cleanly separates write path (commands/events) from read path (projections/queries).

🤖 Agent Responsibilities in CQRS/ES¶

Agent	Skills
`Backend Developer Agent`	`GenerateCQRSHandlers`, `EmitProjections`, `RouteAggregateEventFlow`
`Domain Modeler Agent`	`GenerateEventSourcedAggregate`, `ApplyEventMethod`
`Infrastructure Engineer Agent`	`GenerateEventStoreAdapter`, `ConfigureProjectionStore`
`Test Generator Agent`	`GenerateCQRSFlowTests`, `ValidateProjectionAccuracy`

🧪 Example: Event-Sourced Aggregate¶

public class BookingAggregate : AggregateRoot
{
    public void Apply(AppointmentBooked e) { ... }

    public void Book(...) {
        AddDomainEvent(new AppointmentBooked(...));
    }
}

→ Events are persisted, applied, and used to reconstruct state.

🧱 Infrastructure Considerations¶

Agents may emit:

EventStoreRepository.cs (for event persistence)
Bicep modules for Event Hub, Service Bus, or EventStoreDB
Projection storage (SQL, Cosmos, Elastic)
Configuration for snapshot intervals, replay boundaries, and retention policies

🔄 CQRS Flow (Simplified)¶

sequenceDiagram
  participant Client
  participant CommandHandler
  participant Aggregate
  participant EventStore
  participant Projection

  Client->>CommandHandler: BookAppointmentCommand
  CommandHandler->>Aggregate: Execute
  Aggregate->>EventStore: Append AppointmentBooked
  EventStore->>Projection: Emit to AppointmentsReadModel

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

✅ All flows are agent-generated, traced, and validated via traceId.

📊 Studio Support¶

CQRS mode toggle in module blueprint UI
Visual split between read and write models
Projection viewer and event store inspector
Test coverage per flow (command → event → projection)

✅ Summary¶

CQRS and Event Sourcing are first-class supported patterns, but only applied when specified in blueprints
Agents generate fully separated write/read paths, event stores, and read models
This provides scalability, auditability, and traceable automation in high-complexity domains

🛡️ Strategic Anti-Corruption Layers (ACLs)¶

In ConnectSoft, Anti-Corruption Layers (ACLs) are essential for protecting the integrity of bounded contexts and aggregates. They prevent external systems, third-party APIs, or cross-domain services from introducing concepts that leak into your domain model.

“The ACL is a semantic firewall — it translates foreign language into your domain’s terms.”

ACLs are generated by agents to ensure that each context remains isolated, pure, and testable, while still integrating safely with the outside world.

🧠 Why ACLs Matter in AI-Generated Systems¶

Risk Without ACL	Consequence
External concepts leak into core domain	Domain logic becomes polluted and inconsistent
Hardcoded HTTP/API/DB calls in domain layer	Testability and automation reliability break
No version protection	Upstream changes cause silent downstream corruption
Multi-context integration becomes implicit	Coordination and agent orchestration drift

✅ ACLs preserve the semantic clarity and clean layering required for large-scale automation.

📘 Blueprint Example → ACL Trigger¶

integrations:
  - source: ExternalCRM
    contract: ContactSynced
    mapTo: ClientUpdated
    adapter: CrmClient
    isolation: anti-corruption

→ Triggers agents to generate:

CrmClientAdapter.cs
ContactDto → ClientUpdatedEvent mapper
ClientUpdated.cs domain event
IntegrationTest_CrmSync.feature

🧩 Agent Roles in ACL Generation¶

Agent	Skills
`Infrastructure Engineer Agent`	`GenerateIntegrationAdapter`, `ConfigureHttpClient`, `SecureOutboundCalls`
`Event-Driven Architect Agent`	`MapExternalEvent`, `DefineACLBoundary`
`Domain Modeler Agent`	`GenerateTranslatedDomainEvent`, `ProtectAggregateFromExternalLeakage`
`Documentation Writer Agent`	`DocumentIntegrationContract`

🧱 Clean Placement of ACLs¶

ACL artifacts are placed in:

/Infrastructure/Adapters/ExternalCRM/
  - CrmClient.cs
  - CrmToDomainMapper.cs
  - CrmConfig.cs

Domain does not know about CRM — all translation occurs via adapter and published domain event.

🔁 ACL Translation Patterns¶

Source	ConnectSoft Layer
External Event (e.g., `ContactSynced`)	Translated into a `DomainEvent` (e.g., `ClientUpdated`)
External API Response	Mapped into a ValueObject or DTO
External Command	Wrapped by orchestrator → routed to clean App layer

✅ This preserves bounded context semantics, even in collaborative flows.

🧪 Agent-Generated Tests¶

ACLs include:

Integration test with stubbed external API
Mapper unit test: DTO → Event
Domain event emission test after external call
Config test for endpoint, timeout, auth headers

🔒 Security and Observability¶

ACLs enforce:

Isolation of authentication tokens/secrets via config
TraceId propagation across external requests
Circuit breakers and retry policies by default
ExternalCallStarted, ExternalCallSucceeded, ExternalCallFailed events for observability

Studio shows:

ACL boundary mapping
Integration health metrics
Agent skill history for ACL interactions

✅ Summary¶

Anti-Corruption Layers in ConnectSoft are automatically generated to protect core domains from upstream system leaks
ACLs are placed in infrastructure, emit domain-native events, and are fully testable, observable, and secure
This ensures that integrations are modular, aligned with Clean Architecture, and automation-safe

⚠️ Clean Architecture Anti-Patterns¶

Even in an AI-driven system like ConnectSoft, architectural integrity can be compromised if generated code deviates from core Clean Architecture principles. To ensure consistency, safety, and long-term maintainability, we actively document and defend against a set of Clean Architecture Anti-Patterns.

“Architectural decay starts with one broken boundary. The platform makes sure it ends there too.”

This cycle catalogs what to avoid when generating, validating, or reviewing AI-generated services in the factory.

❌ 1. Anemic Domain Models¶

Symptom: Entities contain only properties, no behavior.

Consequence:

Business rules leak into handlers or infrastructure
No central enforcement of invariants
Hard to test and evolve

✅ Fix: Use aggregates and value objects with rich methods and domain events.

❌ 2. Logic in Infrastructure¶

Symptom: Business logic inside adapters, mappers, or repositories.

Consequence:

Coupling to frameworks or external systems
Hard to trace or test behavior
Domain becomes passive and infrastructure becomes fragile

✅ Fix: Keep logic in Domain and Application layers only. Use interface-based adapters.

❌ 3. Cross-Layer References¶

Symptom: Infrastructure references Application; Application references Infra.

Consequence:

Violates dependency inversion
Prevents test isolation
Breaks modular generation

✅ Fix: Only Infrastructure → Application allowed via inversion. Domain is always inward-facing.

❌ 4. Controller/Handler Bloat¶

Symptom: Controller or command handler performs validation, logic, mapping, and persistence.

Consequence:

Difficult to test and regenerate safely
Low reusability
Confusing agent responsibilities

✅ Fix: Use separate validators, services, and domain entry points.

❌ 5. Blueprint Misalignment¶

Symptom: Generated code doesn’t match the blueprint (wrong contracts, events, or paths).

Consequence:

Coordination flows break
Orchestrators fail to resume
Reviewers lose trust in generation quality

✅ Fix: Enforce traceable mapping between blueprint section → agent skill → generated artifact.

❌ 6. Test Coverage Gaps¶

Symptom: Tests not generated for use cases, events, or queries.

Consequence:

Low automation trust
Uncaught errors in downstream flows
Broken release confidence

✅ Fix: Require test suite per command/event. Validate coverage threshold in CI.

❌ 7. Misplaced Integration Logic¶

Symptom: External API logic placed directly in handlers or application services.

Consequence:

Breaks bounded context
Pollutes business workflows
Reduces tenant isolation and testability

✅ Fix: Route external interactions through ACLs and infrastructure adapters.

❌ 8. Ignoring Tenant Context¶

Symptom: Multi-tenant modules with no tenant scoping in repositories or services.

Consequence:

Data leakage risk
Invalid deployments
Failed governance audits

✅ Fix: Enforce tenantId injection, validation, and partitioning at adapter layer.

✅ Clean Architecture Guardrails in ConnectSoft¶

Anti-Pattern	Prevented By
Anemic model	Domain Modeler Agent + Blueprint constraints
Cross-layer refs	Validators in CI + skill-to-layer metadata
Logic leakage	Templates enforce role-based file structure
Test gaps	`TestSuiteRequired` event + Orchestrator gating
Tenant violations	`TenantScopeRequired` enforcement in blueprint schema

✅ Summary¶

Clean Architecture anti-patterns are actively prevented through templates, validators, and agent scoping
These practices ensure that ConnectSoft-generated modules are maintainable, modular, and testable at scale
Awareness of anti-patterns helps reviewers, prompt authors, and agent curators build better workflows

✅ Summary and Design Rules¶

Clean Architecture and Domain-Driven Design (DDD) are foundational principles in ConnectSoft — not for aesthetic reasons, but because they enable AI agents to generate modular, scalable, and safe software autonomously.

Over the previous 19 cycles, we’ve shown how these principles empower:

📦 Modular generation of thousands of services
🔁 Agent collaboration through contracts and layering
🧠 Context-aware automation based on domain boundaries
🛡️ Safe regeneration, validation, and governance
🧪 Full test coverage and traceability across flows

🧠 Core Principles Recap¶

Principle	Outcome
Bounded Contexts	Agents operate within well-scoped modules and domains
Layered Architecture	Prompts, skills, and outputs map cleanly to responsibilities
Domain-Centric Modeling	Aggregates, events, and entities reflect business meaning
Infrastructure Decoupling	Adapters can be regenerated or replaced without risk
Prompt & Skill Alignment	Each output is intentional, traceable, and contract-bound
Test as Spec	Every use case, event, and behavior is verifiable
Tenant Isolation	Multi-tenant SaaS is secure and maintainable by design
Observability	Agents, artifacts, and flows are all tracked by metadata and events

📋 Clean Architecture Checklist for ConnectSoft Agents¶

✅ Blueprint & Structure¶

Each blueprint has a declared boundedContext, aggregate, and layeredSections
Use cases are defined via commands, queries, and expectedEvents

✅ Domain Layer¶

Aggregates enforce business rules and emit domain events
Entities contain behavior, not just properties
No references to infrastructure or application services

✅ Application Layer¶

Handlers are thin and use services or aggregates for logic
Output DTOs and events are mapped clearly
Prompt-generated handlers are idempotent and testable

✅ Infrastructure Layer¶

Repositories and services are adapter-based
Tenant context is injected and validated
No domain or application logic lives here

✅ Entry Points¶

Controllers and APIs call application handlers only
OpenAPI contracts match handler signatures
Routing supports multitenancy and modular deployment

✅ Testing & Validation¶

Each use case has a SpecFlow + unit test
Event flow tests validate event emission and consumption
Generated tests pass CI with required coverage thresholds

✅ Governance¶

Each artifact has traceId, agentId, skillId, and layer
Prompt + blueprint → output mappings are recorded
Orchestrators validate required outputs before release

📦 Platform-Integrated Enforcements¶

Enforcement	Where Applied
Layer scoping	Templates, orchestrators, Studio validation
Agent execution boundaries	Skill metadata + agent manifest
Artifact placement	CI validators + execution metadata
Test contract enforcement	QA Agent + feedback loop
Clean regeneration	FSM-aware re-execution logic

🧠 Final Thought¶

“Clean Architecture and DDD make agentic software generation possible — scalable, traceable, and safe.”

With these principles, ConnectSoft transforms prompts into blueprints, blueprints into services, and services into sustainable products — without compromising quality, modularity, or compliance.