// Domain-Driven Design as a lens for system architecture — bounded contexts, aggregates, ubiquitous language, context mapping, domain events, and strategic vs tactical patterns. Use when modeling complex business domains, defining service boundaries, or evaluating whether a system's structure reflects its domain.
Use when the /systems-design mode is active. 9-phase structured design methodology -- problem framing, system classification, constraints, candidate architectures, tradeoff analysis, risk review, refinement, migration planning, and documentation. Governs conversation flow, delegation patterns, and user validation checkpoints.
Use when the /systems-design-review mode is active. 7-step design review methodology -- understand the design, classify the system, evaluate against codebase, adversarial analysis, tradeoff validation, synthesis, and action items. Governs conversation flow, delegation patterns, and user validation checkpoints.
Adversarial review of a system design from 6 critical perspectives -- SRE, security, staff engineer, finance, operator, and developer advocate. Produces a unified risk assessment. Use for INTERACTIVE on-demand reviews during a design conversation (/adversarial-review). For RECIPE-DRIVEN reviews (where prior step context is needed), use the systems-design-critic agent instead.
Domain patterns for Azure cloud architecture — compute selection, managed services, identity (Entra ID), networking, data platform, messaging, deployment, cost management, and operational patterns. Use when designing or evaluating a system deployed on Microsoft Azure.
Domain patterns for peer-to-peer system architecture — network topologies, NAT traversal, peer discovery, data distribution, consistency without central authority, identity and trust, and incentive mechanisms. Use when designing or evaluating a decentralized, peer-to-peer, or mesh-networked system.
Domain patterns for single-page application architecture — client-side routing, state management, rendering strategies, authentication, performance, and offline support. Use when designing or evaluating a browser-based SPA, progressive web app, or rich client-side application.
| name | design-philosophy-domain-driven |
| description | Domain-Driven Design as a lens for system architecture — bounded contexts, aggregates, ubiquitous language, context mapping, domain events, and strategic vs tactical patterns. Use when modeling complex business domains, defining service boundaries, or evaluating whether a system's structure reflects its domain. |
DDD as a thinking tool for aligning system architecture with business reality.
Most systems fail not because of bad technology choices but because their structure doesn't match the problem they're solving. Domain-Driven Design is a response to that observation: the shape of your software should reflect the shape of your business domain.
This sounds obvious. In practice, it's rare. Most codebases are organized around technical concerns (controllers, services, repositories) rather than domain concepts (orders, shipments, policies). The result is code where you can't find the business logic — it's scattered across layers, buried in translation code, and duplicated in ways that diverge over time.
DDD provides a set of thinking tools for fixing that. Some are strategic (how to draw boundaries), some are tactical (how to model within a boundary), and the community is guilty of conflating the two. The strategic tools are almost universally valuable. The tactical tools are situational.
This skill focuses on applying DDD to real architecture decisions. Not a glossary of Evans-book terminology — a thinking framework for when you're staring at a system that doesn't make sense and need to figure out where the boundaries should be.
Every bounded context should have a language shared by developers, domain experts, product managers, and the code itself. The same words appear in conversations, user stories, class names, database columns, and API contracts. No translation. No "well, in the code we call it X but the business calls it Y."
This is the most important idea in DDD, and the one most teams skip because it feels soft. It isn't.
Language mismatches are the leading indicator of boundary problems. When developers need a mental mapping table between business terms and code terms, one of two things is true:
rule_set — and over time, the code drifts because the developers don't attend the meetings where "policy" semantics get refined.PriceAdjustment, Rebate, PromoCode, and CouponRedemption, your ubiquitous language has collapsed. Choose one term and make everyone use it.toBusinessModel() / fromBusinessModel() adapter is a place where meaning gets lost. Some translation is inevitable (at context boundaries), but translation within a context means the model is wrong.A team that can't agree on what to call something is a team that hasn't agreed on what it does. Naming debates aren't bikeshedding — they're domain modeling. Take them seriously.
A bounded context is a linguistic and model boundary. Within a bounded context, every term has exactly one meaning, and the domain model is internally consistent. Across bounded contexts, the same word can (and often does) mean different things.
This is the single most valuable concept in DDD for working architects. If you take nothing else from the entire philosophy, take this.
"Order" in the Sales context means a customer's expression of intent to purchase — it has line items, a customer reference, maybe a discount code. "Order" in the Fulfillment context means a set of items to be picked, packed, and shipped — it has warehouse locations, carrier assignments, weight calculations. "Order" in the Billing context means a set of charges to collect — it has payment methods, tax calculations, invoice line items.
These are not the same object with different views. They are fundamentally different models of different aspects of the business. Forcing them into one Order class creates a god object that serves nobody well.
| Bounded Context Boundary | Architectural Manifestation |
|---|---|
| Different meaning of same term | Separate services or modules with explicit contracts |
| Different rate of change | Separate deployable units |
| Different team ownership | Separate repositories or strong module boundaries |
| Different data consistency requirements | Separate databases or schemas |
A bounded context doesn't have to be a microservice. It can be a module within a monolith, a namespace, a separate schema in the same database. The boundary is about model isolation, not deployment topology.
For any service or module, ask: "Does every term in this codebase mean the same thing to everyone who touches it?" If the answer is no, you have either:
if (order.type == SALES) ... else if (order.type == RETURN) ... is a context boundary screaming to get out.Building one "canonical model" that every service shares. This feels like good engineering — one source of truth! In practice, it creates coupling so tight that no team can change anything without coordinating with every other team. The canonical model becomes the lowest-common-denominator model that satisfies nobody.
Each bounded context owns its own model. Communication between contexts happens through well-defined contracts, not shared objects.
Bounded contexts don't exist in isolation. They relate to each other — data flows between them, one depends on another, teams negotiate interfaces. Context mapping is the discipline of explicitly documenting these relationships and choosing the right integration pattern for each.
Shared Kernel: Two contexts share a subset of the model. Both teams own it jointly. This is high-coupling — use only when two contexts are so closely related that separate models would be absurd, and the teams trust each other enough to co-own code.
Customer-Supplier: One context (supplier/upstream) provides data or services that another context (customer/downstream) consumes. The supplier accommodates the customer's needs in their API.
Conformist: The downstream context accepts the upstream's model as-is, without trying to translate. "We'll use their data structures because fighting it isn't worth the cost."
Anti-Corruption Layer (ACL): The downstream context builds a translation layer that converts the upstream's model into its own domain language. The upstream model never leaks into the downstream code.
Open Host Service: The upstream context provides a well-defined, versioned protocol (an API) for any downstream consumer, rather than custom integrations per consumer.
Published Language: A shared interchange format (like a standard schema, protocol buffer definition, or industry-standard format) used for communication. Often paired with Open Host Service.
Ask two questions:
Context maps reflect power dynamics between teams. A team that "conforms" to another team's model is organizationally subordinate to them for that integration, whether anyone admits it or not. An anti-corruption layer is an organizational declaration of independence: "We will not let your model dictate our design."
Making these dynamics explicit is one of the most valuable things context mapping does. It turns invisible coupling into a diagram you can argue about.
An aggregate is a cluster of domain objects treated as a single unit for data changes. Every aggregate has a root entity (the aggregate root) that is the only object external code can reference directly. All modifications to the aggregate go through the root.
The aggregate boundary is a consistency boundary: everything inside an aggregate is guaranteed to be consistent after a transaction. Everything across aggregates is eventually consistent.
The most common DDD mistake is making aggregates too large. The temptation is to put everything that's "related" into one aggregate. An Order aggregate that contains LineItems, ShippingAddress, PaymentInfo, CustomerPreferences, and AuditHistory is too large because:
Order, you have unnecessary contention.A single business operation should modify at most one aggregate. If you find yourself needing to update two aggregates in one transaction, you have one of three problems:
Order and its LineItems must add up correctly at all times — they're one aggregate. An Order and the customer's LoyaltyPoints can be eventually consistent — they're separate aggregates.Order aggregate boundary. If there's no invariant to protect, you might not need an aggregate.Aggregates reference each other by identity (ID), not by direct object reference. The Order aggregate holds a customerId, not a Customer object. This enforces the boundary — you can't accidentally reach into another aggregate's internals.
If your domain is essentially CRUD — create a record, read it, update some fields, delete it — aggregates add complexity without value. Aggregates exist to enforce business invariants in domains with complex rules. A blog post system doesn't need them. An insurance claims processing system probably does.
A domain event represents something meaningful that happened in the domain. OrderPlaced, PaymentReceived, ClaimDenied, PolicyRenewed. These are business-meaningful occurrences, not infrastructure artifacts.
The key distinction: OrderPlaced is a domain event. RowInserted is not. CustomerUpgraded is a domain event. CacheMissed is not. Domain events are named in the ubiquitous language and would make sense to a domain expert.
Domain events serve three purposes:
Order is placed, Inventory needs to be decremented. These are separate aggregates. Order publishes OrderPlaced; an event handler updates Inventory. This is eventual consistency without coupling.OrderPlaced; the Fulfillment context subscribes and creates a shipment. Each context reacts in its own terms, using its own model.Good domain events:
OrderPlaced, not PlaceOrder (that's a command).OrderPlaced followed by OrderCancelled).Event storming is a collaborative workshop technique for discovering domain events, commands, aggregates, and bounded contexts. It's the most effective DDD discovery technique because it's inclusive — domain experts participate directly.
The basic process:
Event storming in 2-3 hours will teach you more about the domain than weeks of reading requirements documents.
OrderPlaced tells you what happened. It doesn't tell the fulfillment system what to do — the fulfillment system decides that based on its own rules. Events inform; commands instruct.DDD has two halves, and they're not equally valuable:
Strategic DDD — bounded contexts, context mapping, subdomain classification, ubiquitous language. This is always worth doing when you have a complex business domain. It doesn't require any specific code patterns. It's about understanding the problem space and drawing boundaries.
Tactical DDD — entities, value objects, aggregates, repositories, factories, domain services, specifications. This is a set of code-level patterns for implementing domain logic within a bounded context. It's optional. Use it when the domain is genuinely complex.
A team reads the Evans book, gets excited, and builds an OrderAggregate with an OrderRepository and an OrderFactory and LineItemValueObject for... a system that creates, reads, updates, and deletes orders with no complex business rules.
The result: mountains of boilerplate wrapping what could have been a simple ActiveRecord model. Every query requires navigating repository abstractions. Every field change requires going through the aggregate root. The code is harder to understand, not easier.
Tactical DDD is for domains where the business rules are complex enough to justify the modeling overhead. Insurance policy calculations. Trading system risk management. Healthcare claims adjudication. Not a task management app.
Not all parts of a business domain are equally important or complex. DDD classifies subdomains into three types, and this classification should drive your investment:
Core Domain: The thing that gives your business a competitive advantage. This is where you invest your best engineers, apply rigorous domain modeling, and potentially use tactical DDD patterns. A logistics company's route optimization. A trading firm's pricing engine. A healthcare company's claims processing rules.
Supporting Domain: Necessary for the business but not differentiating. Your logistics company needs a driver scheduling system, but it doesn't need to be world-class — it just needs to work correctly.
Generic Domain: Problems that have been solved by others. Authentication. Email sending. Payment processing. File storage.
| Question | If Yes | If No |
|---|---|---|
| Are there complex business rules beyond CRUD? | Consider tactical DDD | Use simpler patterns |
| Do domain experts exist and are they accessible? | Strategic DDD is viable | Focus on data modeling |
| Is this a core domain? | Invest in deep modeling | Keep it simple |
| Will the model evolve significantly? | Tactical patterns help manage change | YAGNI |
| Is the team experienced with DDD? | Full DDD is feasible | Start with strategic only |
DDD is not a universal architecture philosophy. It's a tool for a specific class of problems. Applying it to the wrong problem creates worse software, not better.
The application is fundamentally CRUD. If the system's job is to accept data, validate some fields, store it, and retrieve it — DDD adds ceremony without value. A content management system, a simple inventory tracker, a settings page. Use a straightforward data-centric architecture. Rails-style MVC. Simple service + repository. Don't fight it.
The domain has no rich business rules. DDD's value comes from encoding business rules in domain objects. If the business rules are "this field is required" and "this number must be positive," you don't need a domain model — you need input validation.
Domain experts don't exist or aren't accessible. DDD is a collaborative discipline. If you can't sit down with someone who deeply understands the business domain and iterate on the model together, you're guessing. And guessing at domain models produces worse results than not having a domain model.
The team is too small. Bounded contexts imply maintenance overhead — separate models, integration contracts, mapping code. A team of two maintaining four bounded contexts is going to spend more time on infrastructure than business logic. For small teams, a well-organized monolith with clear module boundaries is usually better.
You're building a data pipeline or ETL system. These systems are about transforming and moving data, not about modeling business behavior. Data engineering patterns (staging, transformation, loading, reconciliation) are more appropriate than domain patterns.
The domain is well-understood and stable. DDD's modeling rigor pays off when the domain is complex and evolving. If you're building the 500th e-commerce checkout and the business rules are standard, you don't need event storming to discover what "add to cart" means.
Applied dogmatically. "We must have aggregates because we're doing DDD" is the worst reason to have aggregates. Every DDD pattern has a cost. If you can't articulate the specific benefit it provides in your specific context, you shouldn't use it.
Ask yourself: "Is this domain complex enough that the cost of modeling will be repaid by the clarity of the model?" If you hesitate, the answer is probably no. Start simple. You can always introduce DDD patterns later when the complexity demands them. You can rarely remove them once the team has committed.
Prep (30 min before):
Phase 1 — Chaotic Exploration (30 min):
Phase 2 — Timeline (30 min):
Phase 3 — Commands and Actors (30 min):
PlaceOrder command -> OrderPlaced event.Phase 4 — Aggregates and Boundaries (30 min):
Phase 5 — Debrief (15 min):
When you inherit a codebase and suspect the boundaries are wrong:
You don't rewrite a monolith into bounded contexts overnight. The strangler fig approach:
Step 1 — Identify one context to extract. Choose the one with the clearest boundary and the most pain. A subsystem that changes frequently but whose changes always conflict with unrelated work is a good candidate.
Step 2 — Define the contract. Before moving any code, define the API between the context being extracted and the rest of the system. This is your anti-corruption layer. It might be a function interface, an event bus, or an HTTP API.
Step 3 — Duplicate, don't delete. Create the new context's model alongside the old one. Run both in parallel. The new context gets new functionality; the old code handles existing flows. Gradually migrate callers.
Step 4 — Strangle the old code. As consumers migrate to the new context's API, the old code paths get less traffic. When traffic hits zero, delete the old code.
Step 5 — Repeat. Each extraction makes the remaining monolith simpler and the next extraction easier.
| Situation | Recommendation |
|---|---|
| Complex domain with rich business rules | Strategic + tactical DDD |
| Complex domain, team new to DDD | Strategic DDD only (bounded contexts, ubiquitous language) |
| Multiple teams working on one system | Bounded contexts aligned to team boundaries |
| Integrating with legacy systems | Anti-corruption layer |
| Simple CRUD application | Skip DDD entirely |
| Unsure if domain is complex enough | Start without DDD, introduce it when pain appears |
| Domain experts available and engaged | Event storming -> bounded contexts -> iterative modeling |
| Domain experts unavailable | Data modeling + clean architecture. Revisit DDD when experts appear. |