| name | architecture-patterns |
| description | Use when selecting architecture patterns for a new feature, performing Event Modeling, defining bounded contexts, choosing DDD tactical patterns, evaluating pattern fitness, or understanding how patterns compose. Covers Event Modeling methodology, DDD strategic design, DDD tactical patterns, Clean Architecture, CQRS, and Event Sourcing. |
Architecture Patterns
Overview
A catalogue of architectural patterns used in Clean Architecture + DDD + Event-Driven systems.
Core principle: Patterns are tools — select based on problem, not preference. Every pattern added to a design must be justified by a story or a quality attribute requirement. YAGNI applies to architecture.
The patterns in this skill compose in a specific order: Event Modeling → DDD Strategic → DDD Tactical → Clean Architecture → CQRS, with Event Sourcing applied at the Domain/Infrastructure boundary when history has value.
Event Modeling
BDD-first methodology to model system behaviour as a timeline of events. It is the starting point for every DESIGN session.
Core Concepts
| Concept | Definition | Example |
|---|
| Command | An expression of user or system intent. Imperative mood. May be rejected. | CheckEligibility, SubmitApplication |
| Event | An immutable fact that records a state change. Past tense. Cannot be rejected. | EligibilityChecked, ApplicationSubmitted |
| Read Model | A query output optimised for a specific view. No mutation. | EligibilityResult, ApplicationSummary |
Timeline Structure
Commands cause Events. Events update Read Models. The timeline reads left to right:
[Command] → [Event] → [Read Model]
Each vertical grouping of Command + Event + Read Model is a Slice — the minimum unit of deliverable business value.
How to Build a Timeline from Stories
- Brainstorm Events from stories. Ask: "What facts must be recorded?" Write events on sticky notes.
- Group by aggregate or context. Events that share a consistency boundary belong to the same aggregate.
- Identify Commands that cause each event. Ask: "What action triggered this fact?"
- Identify Read Models consumed before each command. Ask: "What does the user need to see before they act?"
- Define Slices. One slice = one command + its resulting event(s) + the read model that surfaces the result.
Mermaid Notation
timeline
title Eligibility Check — Event Timeline
section Command
CheckEligibility : Submitted by Driver
section Event
EligibilityChecked : Raised by EligibilityAggregate
section Read Model
EligibilityResult : Consumed by Driver UI
Colour coding convention (for tooling that supports it):
- Commands → blue
- Events → orange
- Read Models → green
Relationship to Gherkin
Each slice maps to one or more Gherkin scenarios:
- The Given clause describes the pre-existing state (often a prior event)
- The When clause maps to the Command
- The Then clause maps to the Event and/or Read Model outcome
Auto-Insurance Domain Example
Eligibility Check flow:
- Command:
CheckEligibility (Driver, driverId, requestedAt)
- Event:
EligibilityChecked (driverId, result: Eligible|Ineligible, reason?)
- Read Model:
EligibilityResult (eligible: bool, validUntil?, rejectionReason?)
Application Submission flow:
- Command:
SubmitApplication (applicantId, policyType, vehicleInfo)
- Event:
ApplicationSubmitted (applicationId, submittedAt, status: Pending)
- Read Model:
ApplicationStatus (applicationId, status, submittedAt)
Common Mistakes
| Mistake | Why it matters | Fix |
|---|
| Modelling implementation steps instead of business events | Creates a technical model, not a business model | Reframe in past tense business facts |
| Missing Read Models | Queries become undefined; DISTILL phase can't produce query scenarios | Identify every query the user needs before acting |
| Too many aggregates | Inflates complexity; over-splits consistency boundaries | Group events that must be consistent with each other |
| Commands that cannot fail | Suggests you are modelling state changes, not intent | All commands can be rejected — model the rejection event |
DDD Strategic Design
Bounded Contexts
A Bounded Context is the explicit boundary within which a domain model applies. Within the boundary, every term in the Ubiquitous Language has exactly one meaning.
Identification heuristics:
- Different teams → likely different contexts
- Same word, different meaning → definitely different contexts
- Different rate of change → consider separate contexts
- Separate database or deployment → natural context boundary
Context Mapping Patterns
| Pattern | Relationship | When to use | Risk |
|---|
| Upstream/Downstream | One context feeds another | When one context's model drives another's | Downstream is coupled to upstream changes |
| Conformist | Downstream adopts upstream's model | When upstream is powerful and the cost of translation is too high | Downstream polluted by upstream concepts |
| Anti-Corruption Layer (ACL) | Downstream translates upstream's model | When upstream uses a different or legacy model | Translation cost; must be maintained |
| Shared Kernel | Two contexts share a subset of the domain model | Small shared concepts between close teams | Changes to shared kernel must be agreed by both teams |
| Partnership | Two contexts co-evolve | Equal teams with strong alignment | High coordination overhead |
| Open Host Service | Upstream publishes a versioned API | When many downstreams consume the same upstream | API versioning discipline required |
| Published Language | Open Host Service uses a shared language (e.g., events schema) | Event-driven integration between contexts | Schema governance needed |
Subdomain Classification
| Subdomain | Definition | Investment | Examples in auto insurance |
|---|
| Core | The competitive advantage of the business | Build, invest, DDD deep dive | Eligibility engine, risk scoring |
| Supporting | Necessary but not differentiating | Build or buy, standard patterns | Document management, notifications |
| Generic | Commodity functionality | Buy or use off-the-shelf | Authentication, payment processing |
Ubiquitous Language
- Every term means the same thing within a bounded context
- The same term may mean something different in another context — this is correct
- Document the language in a glossary per context
- Code, tests, and documentation use the same terms — no translations inside a context
Context Map Mermaid Notation
graph LR
EligibilityContext -->|ACL| PolicyContext
PolicyContext -->|Conformist| BillingContext
EligibilityContext -->|Published Language| NotificationContext
Common Strategic Mistakes
| Mistake | Symptom | Fix |
|---|
| Big Ball of Mud | One context for everything; all models coupled | Split by team ownership or language boundary |
| Anemic Domain | All logic in application services; domain objects are data bags | Move invariants back into aggregates |
| Over-splitting | 15 tiny contexts with no clear purpose | Merge contexts that share a language and team |
DDD Tactical Patterns
Aggregate
Definition: A cluster of entities and value objects with a consistency boundary. Changes are always atomic within an aggregate.
Rules:
- One root entity (the Aggregate Root) — all external access goes through the root
- Consistency boundary: invariants are enforced within the aggregate, never across aggregates
- One Repository per aggregate
- Reference other aggregates by ID only — never hold a reference to another root
Size guideline: Prefer small aggregates. Large aggregates cause contention and complexity. If an aggregate has more than 3–5 entities, consider splitting.
Auto-insurance example: EligibilityAggregate — root is Eligibility, contains DriverHistory, RiskScore. It enforces the invariant: "An eligible driver must have fewer than 3 accidents in 5 years."
Entity
Definition: An object with a distinct identity that persists over time. Two entities with the same data are still different entities if their IDs differ.
- Identity types: natural key (e.g.,
DriverId), surrogate key (UUID)
- Mutable state — entities change over their lifecycle
Value Object
Definition: An object that has no conceptual identity. Two value objects with the same data are equal.
- Immutable — never modified after creation
- Equality by value, not by reference
- Self-validating — construction fails if invariants are violated
- Prefer value objects over primitives —
RiskScore instead of int
Auto-insurance example: RiskScore(value: 75), DriverId(value: "DRV-001"), DateRange(from, to)
Domain Event
Definition: An immutable record of something that happened in the domain. Past tense. Raised by an aggregate root.
- Naming: past tense verb phrase —
EligibilityChecked, NOT EligibilityCheckEvent
- Payload: minimal and immutable — only the facts needed to understand what happened
- Raised after state change is committed (inside the aggregate, after invariant enforcement)
- Used for cross-aggregate communication and integration
Repository
Definition: Abstracts the storage mechanism for an aggregate.
- One per aggregate —
IEligibilityRepository, not IGenericRepository<T>
- Interface defined in Application layer — never in Domain or Infrastructure
- No ORM/LINQ leakage in the interface — domain-friendly method names (
GetEligibleDrivers, not FindAll(x => x.Status == "Eligible"))
Domain Service
Definition: Stateless logic that doesn't naturally belong to an aggregate or value object.
When to extract:
- Logic involves multiple aggregates but doesn't belong to either
- Logic involves external lookups that the domain needs
When NOT to extract:
- Logic can live in an aggregate method — keep it there
- Logic is purely infrastructural — put it in the Application layer
Specification
Definition: Encapsulates a business rule as a predicate. Composable with And, Or, Not.
Best use: Complex eligibility rules — compose HasCleanRecord.And(HasMinimumExperience).And(IsLicenceValid).
Clean Architecture
Layer Structure
┌────────────────────────────────────┐
│ API / Presentation │ ← Controllers, DTOs, ViewModels
├────────────────────────────────────┤
│ Application │ ← Use Cases, Commands, Queries
│ │ Application Interfaces (I*Repository, I*Publisher)
├────────────────────────────────────┤
│ Domain │ ← Aggregates, Entities, Value Objects,
│ │ Domain Events, Domain Services
├────────────────────────────────────┤
│ Infrastructure │ ← Persistence, Messaging, External APIs
│ │ Implements Application Interfaces
└────────────────────────────────────┘
Dependency Rule
Source code dependencies point inward only.
- Domain → no dependencies
- Application → depends on Domain only
- Infrastructure → depends on Application (implements its interfaces)
- API → depends on Application (invokes use cases)
Use Case Boundary
The Application layer is the entry point for all external requests. Controllers never touch Domain objects directly — they go through use cases.
Application Interface
Any I/O abstraction (repository, message publisher, external gateway) is defined as an interface in the Application layer. Infrastructure provides the implementation. This keeps the Application layer testable without real infrastructure.
CQRS
Definition
Command Query Responsibility Segregation separates the model used to handle commands (mutations) from the model used to handle queries (reads).
When to Apply
| Signal | Apply CQRS? |
|---|
| Read and write models have different shapes | Yes |
| High read/write ratio | Yes |
| Complex reporting or projection needs | Yes |
| Simple CRUD with no diverging read/write concerns | No — over-engineering |
| Requirement is to "use CQRS" without a concrete problem | No — justify with a problem |
Command Side
- Mutates state
- Raises domain events
- Returns minimal data (acknowledgment, not a view)
Query Side
- Optimised read models — shaped for the consumer
- No mutation
- Can use a different database, cache, or projection
Simple vs Full CQRS
| Variant | Description | When |
|---|
| Simple CQRS | Same database, separate command and query models | Most cases |
| Full CQRS | Separate stores (event store for commands, read DB for queries) | When Event Sourcing is also adopted |
Event Sourcing
Decision Heuristic
Ask: "Does knowing the history of state changes provide business value?"
If NO → do NOT use Event Sourcing.
Use When
- Audit trail is a regulatory or business requirement
- Temporal queries are needed ("What was the eligibility status on 2025-01-15?")
- Multiple diverging read models of the same data are needed
- Complex DDD domains where history enables better invariant enforcement
- Event-driven integration where events are the API
Do NOT Use When
- Simple CRUD with no audit requirement
- No temporal query need
- Team is unfamiliar with the pattern and there is no time to learn
- The domain is Generic or Supporting (commodity functionality)
Aggregate Event Lifecycle
- Receive command (e.g.,
CheckEligibility)
- Load aggregate state (replay events from store or from snapshot)
- Validate command against current state (enforce invariants)
- Emit domain events (e.g.,
EligibilityChecked)
- Apply events to update in-memory state
- Persist events to event store (append-only, with expected version for optimistic concurrency)
Event Store
- Append-only log — events are never updated or deleted
- Versioned — each event has a monotonically increasing version per aggregate
- Immutable — events are facts; they cannot be changed
Projections and Read Models
- Built by replaying events — each projector handles a specific set of event types
- Disposable — projections can be dropped and rebuilt from the event log
- Eventually consistent — the read model lags slightly behind the event store
- Purpose-specific — one projection per read concern (avoid generic projections)
Snapshots
Store the aggregate's current state after every N events to avoid full replay on every load.
- Use when event count per aggregate exceeds ~500 events
- Store snapshot alongside events — load snapshot first, then replay events since snapshot
- Trade-off: storage overhead vs. replay performance
Sagas / Process Managers
Coordinate cross-aggregate workflows. Sit in the Application layer.
- React to domain events
- Issue commands to other aggregates
- Maintain their own process state (saga state is persisted)
- Are NOT aggregates — they are Application-layer orchestrators
Example: EligibilityRenewalSaga — listens for EligibilityExpired event, issues RenewEligibility command to EligibilityAggregate, then NotifyDriver command to NotificationAggregate.
Upcasting
Handle event schema evolution when the structure of an old event type changes.
- Prefer weak schema: ignore unknown fields when loading old events
- For breaking changes: write an explicit upcaster that transforms old format to current format
- Chain upcasters: V1 → V2 upcaster, V2 → V3 upcaster (never skip versions)
Conflict Resolution
Optimistic concurrency: when appending to the event store, pass the expected version. If the stored version differs, a conflict has occurred.
| Scenario | Strategy |
|---|
| Transient (e.g., two concurrent updates from different UI sessions) | Retry — reload and reapply the command |
| Domain-specific (e.g., two agents claim the same appointment slot) | Merge — apply domain logic to determine the correct outcome |
| Critical (e.g., financial transaction double-spend) | Reject — return a conflict error and require user intervention |
Eventual Consistency Mitigation
| Technique | Description |
|---|
| Read-your-own-writes | After a command, return a token; query endpoint waits for projection to catch up to that version before returning |
| Optimistic UI updates | UI applies the expected state change immediately without waiting for projection |
| Causal consistency tokens | Pass a token that represents "everything up to this point was processed" |
Outbox Pattern
Solves the dual-write problem: atomically writing to the event store AND publishing to a message broker.
- Write domain events to the event store
- Write the same events to an outbox table in the same transaction
- A background process reads the outbox and publishes to the message broker
- After successful publish, mark the outbox entry as processed
Avoids the risk of the event store committing but the broker publish failing (or vice versa).
Reservation Pattern
Handles uniqueness constraints (e.g., unique driver licence number) in event-sourced systems.
- Create a separate
ReservationAggregate for the unique key
- Command flow:
ReserveLicenceNumber → LicenceNumberReserved (or LicenceNumberAlreadyReserved)
- The driver registration aggregate only proceeds after receiving confirmation of reservation
Pattern Composition
Patterns compose in a specific order. Start from the outside and work inward:
Event Modeling (what the system does)
→ DDD Strategic Design (where the boundaries are)
→ DDD Tactical Design (what the domain model looks like)
→ Clean Architecture (how layers are structured)
→ CQRS (how commands and queries are separated)
→ Event Sourcing (how state is persisted, when history matters)
→ Sagas (how cross-aggregate workflows are coordinated)
Key composition rules:
- Event Sourcing applies at the Domain/Infrastructure boundary — only when the decision heuristic says yes
- Sagas sit in the Application layer — never embed saga logic in an aggregate
- CQRS and Event Sourcing often appear together but are independent — you can use CQRS without Event Sourcing
Decision Matrix
| Problem type | Recommended pattern | When NOT to use | Notes |
|---|
| Simple CRUD entity | Clean Architecture + Repository | Don't add Event Sourcing or CQRS | Keep it simple |
| Complex business rules with invariants | DDD Tactical (Aggregate + Specification) | Don't use anemic domain model | |
| Audit trail / regulatory compliance | Event Sourcing | Only if history has real business value | Requires infrastructure investment |
| Multiple diverging read models | CQRS with projections | Not needed for simple queries | Read models are disposable |
| Cross-aggregate coordination | Saga / Process Manager | Don't put saga logic in an aggregate | |
| High read/write ratio | CQRS with read-optimised projections | Don't use for simple apps | |
| Complex domain with multiple teams | DDD Strategic + Context Mapping | Overhead for small teams | |
| Event-driven integration | Domain Events + Outbox Pattern | Don't use for in-process only | |
References
- event-modeling.md — Full Event Modeling methodology and notation guide
- ddd-strategic.md — Bounded context identification, context mapping, subdomain classification
- ddd-tactical.md — Aggregate, Entity, Value Object, Domain Event, Repository, Specification
- pattern-catalog.md — Clean Architecture layers and CQRS pattern details
- pattern-selection-matrix.md — Decision table by problem type + composition guide
- anti-patterns.md — 10 architecture anti-patterns with root causes and fixes
- event-sourcing.md — Complete Event Sourcing guide: aggregate lifecycle, projections, sagas, upcasting
