Domain-Driven Design: Bounded Contexts Explained

A customer places an order, support cancels it, fulfillment ships it, and finance issues a refund. The nouns look universal: customer, order, product, payment. It is tempting to put each noun in one shared class and let every part of the company reuse it. Six months later, Order.status has fourteen values, nobody knows which transitions are legal, and changing a field requires a meeting with five teams.

The problem is not poor naming or insufficient abstraction. The same word carries different meanings in different business conversations. Domain-Driven Design (DDD) calls the boundary within which a particular model and language remain consistent a bounded context. It is a semantic boundary first and a software boundary second. Used well, it gives each team a model that is precise for its job while making disagreements between models explicit at integration points.

One Business, Several Truths #

Consider an online retailer. In Sales, a product is something a customer can configure and buy; its important attributes are price, availability, and sales options. In Warehouse, the apparently same product is stock identified by a SKU, dimensions, storage requirements, and bin location. Finance cares about a ledger item, tax category, and recognized revenue. None of these models is the canonical, complete Product. Each is a useful truth for a particular decision.

A bounded context says where one of those truths applies. Inside the Sales context, Product can safely mean an offer. At the Warehouse boundary, the word no longer has authority. The warehouse may call its concept InventoryItem, even when both concepts refer to the same physical thing. That difference is information, not duplication to eliminate.

Boundaries commonly become modules, deployable services, data ownership lines, or some combination of them. They do not have to become microservices. A modular monolith can contain strong bounded contexts with separate packages and schemas. Conversely, two services that import the same domain entities and modify the same tables are not meaningfully bounded.

Ubiquitous language is executable precision #

Within each context, domain experts and engineers develop a ubiquitous language: the vocabulary used in conversations, requirements, tests, APIs, and code. If operations says an order is “allocated” only after every line has reserved stock, code should express allocateOrder, not a generic updateStatus("READY"). The model becomes easier to challenge because business statements map to visible behavior.

The language is local, not enterprise-wide. Sales might “cancel an order” before acceptance, while Fulfillment can only “stop a shipment” after allocation. Forcing both into one verb hides different rules. Record these differences in examples and glossaries, but prefer code that makes them concrete.

Discover Boundaries From Business Friction #

Good boundaries are discovered, not generated from a list of nouns. Start with business capabilities and decisions: selling, pricing, allocating stock, shipping, collecting money, and supporting customers. Then watch where language, rules, rates of change, and ownership diverge.

Useful signals include:

• Different definitions. “Active customer” means eligible to buy in Sales but recently engaged in Marketing.
• Different invariants. Checkout requires a stable quoted price; Catalog can tolerate eventual reindexing.
• Different change cadence. Promotions change weekly while tax calculation changes under regulatory control.
• Different authorities. Warehouse owns available quantity; Sales may cache it but must not invent it.
• Different workflows. A sales order, pick list, shipment, and invoice have related identifiers but distinct lifecycles.

Event storming is a practical discovery technique. Put domain events such as OrderPlaced, StockAllocated, ShipmentDispatched, and PaymentCaptured on a timeline. Add commands, policies, actors, and pain points. Clusters often reveal candidate contexts; ambiguous terms and contested events reveal likely boundaries. Validate each candidate by asking: Which decisions belong here? Which facts does it own? What can change without coordinating with another group?

Do not optimize for the largest possible independent area. A context that contains every checkout dependency is just a distributed monolith drawn as a box. Also avoid tiny contexts for every entity. The target is high semantic cohesion: rules that must remain consistent change together, while unrelated rules communicate through contracts.

Make the Context Map Honest #

A context map shows bounded contexts and the relationships between them. Unlike a component diagram, it includes social and semantic direction: who is upstream, who must adapt, and where translations occur. That information predicts change cost better than arrows labeled “HTTP.”

Here Catalog is upstream of Sales for sellable offers. Sales is upstream of Warehouse for accepted orders, but it is downstream of Shipping for dispatch facts. “Upstream” is relationship-specific; a context is not globally above another.

Relationship patterns and their tradeoffs #

DDD names recurring relationship patterns. The labels matter only when they drive an engineering or team decision.

For example, conforming to a payment provider’s concepts at the HTTP client may be harmless. Letting ProviderChargeStatus control order fulfillment is not. Relationship choice depends on strategic value, model distance, and team leverage, not a rule that every boundary needs an ACL.

Integrate With Contracts, Not Shared Objects #

Cross-context communication should carry facts and requests, not live domain objects. A contract might be an HTTP representation, an event schema, or a batch file. In all cases it needs an owner, documented semantics, compatibility rules, observability, and a retirement plan.

Prefer integration messages shaped around what happened or what is requested: OrderPlaced, ReserveStock, StockRejected. Avoid exporting internal aggregates wholesale. Consumers otherwise couple to fields that were never promises. Include stable identities, units, currency, timestamps, and enough idempotency information to process retries. Version deliberately: additive optional fields are usually safe; renamed meanings are not.

The following TypeScript sketch keeps Sales and Payments models separate. Sales owns the Order aggregate and its invariant: only a placed order awaiting payment may be confirmed. The provider DTO remains outside that model. An anti-corruption layer translates provider-specific statuses, minor currency units, and duplicate webhooks into a small Sales-facing port.

// sales/domain/order.ts
export type OrderId = string & { readonly __brand: 'OrderId' };

export type Money = Readonly<{
  amount: number;
  currency: 'USD' | 'EUR';
}>;

export type OrderLine = Readonly<{
  sku: string;
  quantity: number;
  unitPrice: Money;
}>;

type OrderState =
  | { kind: 'draft' }
  | { kind: 'awaiting-payment'; paymentReference: string }
  | { kind: 'confirmed'; paidAt: Date }
  | { kind: 'cancelled'; reason: string };

export class Order {
  private state: OrderState = { kind: 'draft' };

  constructor(
    readonly id: OrderId,
    readonly lines: readonly OrderLine[],
  ) {
    if (lines.length === 0) throw new Error('An order requires at least one line');
  }

  total(): Money {
    const currency = this.lines[0]?.unitPrice.currency;
    if (!currency) throw new Error('An order requires at least one line');
    if (this.lines.some((line) => line.unitPrice.currency !== currency)) {
      throw new Error('Mixed currencies are not allowed');
    }
    return {
      amount: this.lines.reduce(
        (sum, line) => sum + line.quantity * line.unitPrice.amount,
        0,
      ),
      currency,
    };
  }

  place(paymentReference: string): void {
    if (this.state.kind !== 'draft') throw new Error('Order is already placed');
    this.state = { kind: 'awaiting-payment', paymentReference };
  }

  confirmPayment(paidAt: Date): void {
    if (this.state.kind !== 'awaiting-payment') {
      throw new Error('Only an awaiting-payment order can be confirmed');
    }
    this.state = { kind: 'confirmed', paidAt };
  }
}

// payments/integration/payment-provider.ts
import type { Money, OrderId } from '../../sales/domain/order.js';

type ProviderWebhook = Readonly<{
  event_id: string;
  object: {
    merchant_reference: string;
    state: 'authorized' | 'captured' | 'failed' | 'reversed';
    captured_amount_minor: number;
    currency_code: string;
    captured_at: string | null;
  };
}>;

export type PaymentResult =
  | { kind: 'pending' }
  | { kind: 'paid'; orderId: OrderId; amount: Money; paidAt: Date }
  | { kind: 'rejected'; orderId: OrderId; reason: string };

export interface ProcessedEvents {
  has(eventId: string): Promise<boolean>;
  add(eventId: string): Promise<void>;
}

export class PaymentProviderAcl {
  constructor(private readonly processedEvents: ProcessedEvents) {}

  async translate(webhook: ProviderWebhook): Promise<PaymentResult | null> {
    if (await this.processedEvents.has(webhook.event_id)) return null;

    const orderId = webhook.object.merchant_reference as OrderId;
    const result = this.toDomainResult(webhook, orderId);
    await this.processedEvents.add(webhook.event_id);
    return result;
  }

  private toDomainResult(
    webhook: ProviderWebhook,
    orderId: OrderId,
  ): PaymentResult {
    const payment = webhook.object;
    if (payment.state === 'captured' && payment.captured_at) {
      return {
        kind: 'paid',
        orderId,
        amount: {
          amount: payment.captured_amount_minor / 100,
          currency: this.toCurrency(payment.currency_code),
        },
        paidAt: new Date(payment.captured_at),
      };
    }
    if (payment.state === 'failed' || payment.state === 'reversed') {
      return { kind: 'rejected', orderId, reason: payment.state };
    }
    return { kind: 'pending' };
  }

  private toCurrency(code: string): Money['currency'] {
    if (code === 'USD' || code === 'EUR') return code;
    throw new Error(`Unsupported payment currency: ${code}`);
  }
}

This layer is more than a DTO mapper. It prevents provider language from deciding Sales behavior, rejects unsupported currencies, normalizes money, and handles delivery semantics. In production, storing the processed event and changing order state should participate in a transactional inbox or equivalent atomic workflow; the in-memory-looking interface above only exposes that policy.

Align Teams and Test the Boundary #

A boundary that no team owns will erode. Assign one team authority over each context’s model, data, and published contracts. That team can collaborate with consumers, but consumers should not bypass it with shared database writes. Team topology and model topology need not match forever, yet a many-to-many ownership matrix makes ordinary changes expensive.

Test at three levels. First, domain tests express invariants in ubiquitous language: an empty order cannot exist, mixed currencies are rejected, and payment cannot confirm a draft. Second, ACL unit tests cover every upstream status, malformed value, unit conversion, and duplicate event. Third, contract tests verify the real provider or producer against recorded schemas and compatibility expectations. A small end-to-end test should prove the critical business path, but it should not replace focused tests at the boundary.

Observe integrations as products. Record contract version, correlation and causation identifiers, translation failures, retry count, and dead-letter volume. Alerts should say “Payments rejected an unsupported currency from Provider X,” not merely “consumer failed.” Semantic failures deserve first-class telemetry because retries cannot repair them.

Review the context map when responsibilities, regulations, or teams change. It is a decision record, not architecture wallpaper. If two contexts always change together and translation has no business value, merge them. If one model accumulates conditional rules for unrelated actors, split it. Boundaries are hypotheses about cohesion, refined through delivery.

Common Mistakes and When DDD Is Too Much #

The most common mistake is treating bounded contexts as a service decomposition recipe. Teams draw one service per noun, add asynchronous messaging, and call the result DDD. The outcome has network latency without semantic independence. Start with language and invariants; choose process boundaries later.

Other recurring failures are a shared domain-model package, a shared writable database, integration events copied directly from internal tables, and an “enterprise canonical model” that tries to satisfy everyone. These mechanisms erase local autonomy. Another failure is ceremonial modeling: workshops produce attractive diagrams, but code continues to use generic CRUD records and status strings.

DDD also has real overhead. It asks engineers and experts to model together, maintain contracts, translate concepts, and revisit boundaries. That investment is often unjustified for a straightforward CRUD application, a short-lived campaign, a single-team internal tool, or a domain where rules are simple and stable. A transaction script with clear modules can be the better design.

Use strategic DDD where ambiguity and business rules dominate cost: pricing, fulfillment, risk, scheduling, compliance, or other differentiating capabilities. Use simpler patterns for supporting areas. You can keep a context boundary around a commodity subsystem without building rich aggregates inside it. The goal is not maximum DDD; it is enough modeling to make important decisions safe and changeable.

Takeaways #

• A bounded context defines where one domain model and ubiquitous language are consistent; it is not automatically a microservice.
• Discover boundaries from decisions, invariants, language conflicts, ownership, and change cadence rather than entity lists.
• A context map makes upstream/downstream dependencies and team relationships explicit.
• Integrate through owned, versioned contracts. Use an anti-corruption layer when an external model would distort the local one.
• Align team authority with model and data ownership, then test domain rules, translations, and contract compatibility separately.
• Merge or split contexts as evidence changes, and skip rich DDD when the domain’s complexity cannot repay its cost.

Bounded contexts do not remove disagreement from a business. They put each disagreement at a visible boundary where teams can name it, negotiate it, translate it, and test it. That is what turns a collection of boxes into an architecture capable of evolving.