Domain-Driven Design in NestJS: Bounded Contexts, Aggregates, Repositories (2026)

Q: What is a bounded context in DDD?

A bounded context is a section of the system in which a single ubiquitous language has consistent meaning. "Customer" in a Sales context (a person with a billing address and pipeline stage), "Customer" in a Support context (an account with open tickets and an SLA), and "Customer" in a Billing context (a payer with a payment method and invoicing schedule) are three different concepts that share a name in business conversation but should be three distinct types in code, owned by three distinct bounded contexts. The boundary is the conceptual seam at which translation happens — typically through an Anti-Corruption Layer that maps one context's model into another's. The classic DDD failure is forcing a single "Customer" definition across the whole system; the architectural virtue is naming the contexts, drawing the boundary, and translating explicitly. Bounded contexts are the unit of conceptual integrity, not just code organisation, and they are the most important DDD concept to get right.

Q: How do bounded contexts map to NestJS modules?

One bounded context maps to one or more NestJS modules; never the other way around. A bounded context is a business-meaning boundary; a NestJS module is a technical organisation primitive. A small bounded context (Notification) might be a single NestJS module with one service and a few event handlers. A large bounded context (Order) might be five modules under src/contexts/order/ covering placement, fulfilment, refunds, returns, and reporting. The mistake is treating every NestJS module as its own bounded context — that produces fragmented business meaning, with the Customer concept scattered across user-module, profile-module, preferences-module and auth-module, each owning a piece that can never be reasoned about coherently. The recommended directory structure puts contexts at the top level (src/contexts/sales/, src/contexts/support/) with NestJS modules underneath, and lint rules forbid imports across context boundaries except through declared public interfaces (typically the application service or the published event schema).

Q: What is an aggregate and how do I size it correctly?

An aggregate is a cluster of objects that change together and must be persisted together. It has a root entity (the only thing the outside world references), one or more child entities and value objects, and a set of invariants that must hold at all times. An Order aggregate has the order header as the root, line items as child entities, the shipping address as a value object, and an invariant that the total must equal the sum of line items minus discounts. The aggregate exposes methods that mutate its state and enforce its invariants — never raw setters that let callers put it into an invalid state. Sizing is the most consequential decision: too large and the aggregate becomes a contention hot spot (locking the entire order to update one item); too small and invariants spill across aggregates (the "total = sum of items" rule cannot be enforced because items live separately). The standard guidance: keep aggregates as small as possible while still encompassing all the invariants that must be transactionally consistent. Cross-aggregate consistency is achieved through domain events and eventual consistency, not by enlarging the aggregate.

Q: What is the ideal NestJS folder structure for DDD?

Bounded contexts at the top level, layered architecture inside each: src/contexts/{context}/domain/, application/, infrastructure/, presentation/. The domain layer is pure business logic — entities, value objects, domain services, domain events — with zero framework dependencies (no NestJS imports, no ORM imports). The application layer is use cases and orchestration — application services, command and query handlers, transactional boundaries — depending on the domain plus interfaces (ports) for infrastructure. The infrastructure layer implements those ports — repositories on top of TypeORM, message bus adapters, external API clients — and is the only layer that imports framework-heavy modules. The presentation layer is HTTP — controllers, DTOs, validators — depending on the application layer. The dependency direction (presentation → application → domain ← infrastructure) is the test of correctness: if the domain imports from infrastructure (a TypeORM decorator on a domain entity, for example), the architecture has decayed to the conventional NestJS pattern in which "domain" is a label rather than a real layer.

Q: What is the difference between a real repository and a DAO?

A real repository hides the persistence mechanism completely: the application code asks for an aggregate by ID, gets back a fully-hydrated aggregate, mutates it through its domain methods, and asks the repository to save it. The repository exposes findById, save, and a small number of domain-meaningful queries (findActiveByCustomer). The application does not know whether persistence is PostgreSQL with TypeORM, MongoDB with Mongoose, or an in-memory map for tests. A DAO masquerading as a repository exposes findByEmailContaining, updateStatusToCancelled, incrementViewCount, and twenty other CRUD-shaped methods. It leaks persistence concerns into the application layer, bypasses the aggregate (the status update did not load the aggregate, did not enforce invariants, did not emit a domain event), and makes the architecture brittle. The mapper class translates between the persistence row (columns, foreign keys, ORM types) and the domain aggregate (value objects, child entities, domain methods); without a mapper, the domain is coupled to the database schema and forced to evolve at the database's cadence. Treat mappers as non-optional infrastructure.

Q: How do domain events work in NestJS?

Domain events are facts, expressed in business language, that other contexts may care about: OrderPlaced, InvoiceIssued, SubscriptionRenewed — past-tense statements about something that just happened. The aggregate emits the event when the state change occurs (storing it in an internal events array); the use case extracts events from the aggregate after persistence and publishes them to the event bus; other contexts subscribe via their own handlers. NestJS provides @nestjs/event-emitter for simple in-process events and @nestjs/cqrs for a more structured event/command/query model with built-in saga support. In a modular monolith the bus is in-process (zero network cost, zero broker to operate). When a context is extracted to a separate service, the in-process bus is replaced with a message broker (RabbitMQ, Kafka, AWS SNS/SQS) and event publication must become atomic with the database transaction — which is exactly what the Transactional Outbox pattern solves. The use-case code is unchanged; only the bus implementation differs. Event handlers belong to the receiving context, not the publishing context — the Order context never knows or cares which contexts subscribe to OrderPlaced.

Q: How does DDD compose with the Saga and Outbox patterns?

A Saga is a long-running business process that spans multiple aggregates or contexts — placing an order, charging payment, reserving inventory, shipping the package is a four-step Saga that cannot be done in a single transaction because the steps live in different aggregates (and often different services). The DDD answer is a Saga orchestrator (or a chain of choreographed event handlers) that listens for events and issues the next command, with explicit compensation steps if any step fails. The Saga is itself a domain concept (it has a name, a state machine, and an owner) and should be modelled in the application layer rather than smuggled into infrastructure. The Transactional Outbox pattern guarantees that domain events are published exactly when the database transaction commits — without it, the use case can save the aggregate and then crash before publishing the event, leaving the system inconsistent. With the Outbox, the event is written to an outbox table in the same transaction as the aggregate save, and a separate process polls the outbox and publishes to the broker. Together, DDD + Saga + Outbox + Event-Driven Architecture form the standard pattern for distributed business workflows.

Q: What is the dependency direction rule and why does it matter?

The dependency direction is the test of architectural correctness: the domain layer should compile without any other layer present; the application layer should compile with only the domain layer present; the infrastructure layer should depend on the domain (for the port interfaces) but the domain must never depend on infrastructure. This is the dependency inversion principle applied at architectural scale — high-level policy (domain) does not depend on low-level mechanism (infrastructure); both depend on abstractions (ports/interfaces defined in the domain). If you find a TypeORM decorator on a domain entity, an HttpClient call from inside a value object, or a NestJS @Injectable on something in the domain folder, the dependency direction has been inverted and the architecture has decayed to the conventional pattern where "domain" is a label rather than a real layer. The benefit of correct dependency direction is real: the domain can be unit-tested without any framework, the persistence implementation can be swapped (PostgreSQL to MongoDB, or to an in-memory map for tests) without touching domain or application code, and the business logic remains framework-agnostic so it survives framework migrations.

Q: When is DDD not worth the overhead?

Three situations. First, CRUD-shaped applications with no real domain logic — admin panels, configuration UIs, internal dashboards — have no invariants worth protecting and no ubiquitous language worth preserving. Building them with full DDD layering produces a thousand lines of code where two hundred would suffice, with no benefit. Decision rule: if the business logic can be expressed as "read row, update row, write row," skip DDD and use a thin controller-service-ORM pattern. Second, prototypes and proofs of concept — a throw-away to test a market hypothesis needs to ship in a week and either succeed (rewrite it) or fail (throw it away). Prototypes that get DDD-ified become real products by accident, with technical debt nobody planned to incur. Third, teams without the discipline to maintain it — DDD requires sustained discipline (every PR enforces layer separation, every code review checks ubiquitous language consistency, every developer understands why aggregates exist). A team without buy-in produces a codebase with the DDD folder structure and none of the DDD benefits, which is the worst of both worlds. Save DDD for the parts of the system that have real domain complexity, with teams committed to maintaining it.

Q: What is the ubiquitous language and why does it matter?

The ubiquitous language is the shared vocabulary used by domain experts and developers to talk about the system, and the discipline of carrying that vocabulary unchanged from whiteboard conversations into the code. If the business calls them "shipments," the domain model has a Shipment class — not a DeliveryRequest, not an OrderFulfilment, not an OutboundParcel. If the business distinguishes "subscriptions" from "memberships," the code makes the same distinction with two types, not one type with a flag. The naming discipline matters because it is the bridge between domain experts and developers: when a business user says "the renewal failed," every developer should know exactly which code path is involved, without translation. Vocabularies that drift between business and code produce bugs that take weeks to diagnose because the business and the developers are talking past each other — the business reports a problem with "renewals" and the developers spend three days investigating "subscription updates" before realising they are looking at the wrong code path. The ubiquitous language is enforced through code review, glossaries shared with the product team, and the courage to rename code when the business vocabulary itself evolves.

Satyam Kumar

Retour au blog

microservices-patterns

Domain-Driven Design in NestJS: A Practical Architecture Guide (2026)

By Satyam KumarApril 25, 202619 min read

domain-driven design DDD NestJS architecture bounded contexts aggregates value objects repository pattern domain events anti-corruption layer ubiquitous language hexagonal architecture ports and adapters CQRS event-driven architecture saga pattern transactional outbox TypeORM NestJS modules

Domain-Driven Design in NestJS: A Practical Architecture Guide (2026)

Frequently Asked Questions

Partager l'article

Twitter LinkedIn WhatsApp

Satyam Kumar

Founder & AI Architect, AppScale LLP

Architecte AI & Cloud. J'aide les équipes à construire des systèmes qui scalent pour des millions.

LinkedIn GitHub

Domain-Driven Design in NestJS: A Practical Architecture Guide (2026)

Frequently Asked Questions

Partager l'article

Comments

Leave a comment