DEV Community: Andrew Boyko

CQRS in NestJS: When It's Worth the Complexity

Andrew Boyko — Thu, 02 Jul 2026 14:16:38 +0000

The person most responsible for the industry-standard explanation of CQRS is also the person telling you not to use it. Martin Fowler's bliki entry on CQRS, the page half of the backend world links to when they explain the pattern, says plainly: "you should be very cautious about using CQRS." Not a hedge. Not a "consider the tradeoffs." A direct warning, from the guy whose writeup made the term mainstream.

That's not a contradiction. It's the actual state of the pattern: genuinely useful in a narrow set of cases, and a productivity tax everywhere else. The hard part isn't understanding CQRS. It's telling which side of that line your service is on.

What CQRS Separates

CQRS traces back further than most people assume. Bertrand Meyer's Command-Query Separation principle, from his work on Eiffel, said a method should either change state or return data, never both, at the level of a single function. CQRS takes that idea and moves it up a layer: instead of one function doing one thing, it's your write model and your read model that split. Udi Dahan was applying this to service-oriented systems as early as 2008, formalizing it as "Clarified CQRS" in 2009. Greg Young popularized the term and the modern shape of the pattern around 2010, usually alongside domain-driven design.

The core move: commands change state and return nothing meaningful. Queries return data and change nothing. Once you accept that split, you're free to give commands and queries completely different models, different validation rules, even different storage, because nothing has to reconcile a single "the truth" schema that serves both jobs at once.

The Read/Write Skew That Justifies It

Fowler names two legitimate reasons to reach for CQRS: a domain complex enough that a unified model would need to compromise for both directions, or a real performance requirement to scale reads and writes independently. Everything else is optional complexity dressed up as architecture.

The skew that matters isn't "we have more reads than writes." Almost every system does. It's a structural mismatch: your write side needs rich validation, business rules, and multi-step invariants, while your read side needs to answer questions your write model was never shaped to answer efficiently. A booking system that validates availability, conflicts, and cancellation policy on write, but needs to answer "show me every booking across three time zones grouped by room" on read, has structural skew. A blog with a posts table and a title/body/published_at doesn't, no matter how many more reads than writes it serves.

If your honest answer to "why can't the same model serve both" is "it could, we just don't want to write two queries," that's not skew. That's an excuse.

What the NestJS CQRS Module Gives You

@nestjs/cqrs gives you three buses: CommandBus, QueryBus, and EventBus. All three are built on RxJS Observables, so you can subscribe to the whole stream of commands, queries, or events flowing through your application, not just the individual handler results.

src/scheduling/commands/create-swap-request.handler.ts

@CommandHandler(CreateSwapRequestCommand)
export class CreateSwapRequestHandler
  implements ICommandHandler<CreateSwapRequestCommand>
{
  constructor(private readonly shifts: ShiftRepository) {}

  async execute(command: CreateSwapRequestCommand): Promise<string> {
    const shift = await this.shifts.findById(command.shiftId);
    shift.requestSwap(command.requestedBy, command.reason);
    await this.shifts.save(shift);
    return shift.id;
  }
}

The command handler owns validation and business rules. It doesn't return the shift, a DTO, or anything the frontend would render, just enough to confirm the write happened. A matching query handler pulls from whatever shape is fastest to read, which does not have to be the same tables the command touched.

One detail that catches people off guard: CommandBus, QueryBus, and EventBus are singletons, so combining them with NestJS's request-scoped providers takes extra care. The library handles this by spinning up a new instance of a request-scoped handler for each command, query, or event it processes, rather than sharing one instance across requests. It works, but it's not obvious from the decorator syntax that anything special is happening underneath.

Event handlers run asynchronously and are expected to handle their own exceptions. An event handler that throws doesn't crash the request that published the event, it gets caught, wrapped into an UnhandledExceptionInfo, and pushed onto a separate UnhandledExceptionBus stream.

If nothing is listening to that stream, the failure disappears silently. First time I saw this, I assumed a failing event handler would at least log something by default. It doesn't. You have to wire that up yourself.

CQRS Is Not Event Sourcing

These two get bundled together constantly, partly because they show up in the same tutorials and partly because event sourcing naturally produces a write side and a read side that already look like CQRS. But they're independent decisions.

Event sourcing means your source of truth is an append-only log of events, and current state is a projection computed by replaying them. CQRS means your read and write models are separate. You can event-source without CQRS (replay events into the same model you write through). You can do CQRS without event sourcing (a normal relational write model, plus a denormalized read table kept in sync by a projector). NestJS's CQRS module happens to ship with AggregateRoot and event-emitting building blocks that make it easy to slide into event sourcing, but nothing about CommandBus and QueryBus requires it.

Conflating the two is how projects end up with the operational cost of an event store (replay logic, event versioning, snapshotting) when all they actually needed was a read-optimized table.

The Failure Mode: Applying CQRS to Everything

The most common way teams burn the investment is treating CQRS as a system-wide default instead of a targeted tool. Fowler's own framing: many systems fit a CRUD mental model just fine, and forcing CQRS onto them is "a significant mental leap for all concerned" with no matching payoff.

The failure compounds in a microservices context. If you don't identify your aggregate boundaries correctly first, and then apply CQRS on top of that mistake, you end up splitting a single aggregate's data across services, because the read side "needs" a view that spans what should have been one consistency boundary. That's not CQRS creating the mess, it's CQRS making an existing modeling mistake more expensive to carry.

The rule that scales: apply CQRS to the specific bounded contexts where the skew is real, never to a whole application by default. A platform can have three services where CQRS earns its keep and twelve where a repository and a DTO are all anyone needed.

The Eventual Consistency Tax You're Paying

Splitting the models means the read side can lag the write side. How much depends entirely on your projection mechanism, synchronous in the same transaction, asynchronous via a message queue, or somewhere in between, but the lag is never exactly zero once the models are meaningfully separate.

The concrete version of this problem: a user places an order, and it can take anywhere from a couple of seconds to a couple of minutes before that order shows up in their order history, depending on how the projection pipeline is built. That's not a bug. It's the actual cost of the pattern, and it has to be a product decision, not something the write side discovers by accident when a support ticket comes in asking why a booking "disappeared."

If your UI can't tolerate that lag anywhere in the flow, either the projection needs to be synchronous for that specific path, defeating some of the scaling benefit, or CQRS is the wrong tool for that particular read.

Where I'd Reach for This

On the healthcare platform I work on now, the scheduling side has exactly this shape: writing a shift change means checking coverage rules, skill-level requirements, and conflict windows across a rotation, real domain complexity on the command side, while the read side mostly needs to answer "show me the week" in a dozen different groupings (by provider, by department, by shift type) fast enough for a calendar UI that gets hit constantly. That's read/write skew, not a preference.

Credentialing, on the same platform, mostly isn't. A verification record has a status, an expiration date, and an audit trail. The queries against it are close enough to the write shape that splitting the models would add a synchronization problem without buying anything back. One service, two very different answers to "should this use CQRS," and the difference is the skew, not the domain's importance.

That's the actual decision procedure: not "is this domain important" or "are we doing microservices," but "would the read model and the write model genuinely want to be different shapes, and is the eventual-consistency cost something the product can absorb." If both answers are yes, the complexity Fowler warns about is the complexity you're supposed to be paying for.

Originally published at andriiboyko.com.

Bounded Contexts in a Real Codebase, Not a Diagram

Andrew Boyko — Thu, 02 Jul 2026 14:16:24 +0000

Everyone draws the same diagram. A box for each part of the domain, a straight line from each box to a service, one arrow per box. It's the tidiest picture you'll ever ship in an architecture review, and the moment you try to build it exactly as drawn, it starts to lie to you.

I've now been on both sides of that diagram: the person who drew it with total confidence in year one, and the person who had to explain eighteen months later why the "Credentialing" box didn't match the credentialing service. The mismatch wasn't a mistake. It's what happens when you take a modeling concept and treat it like a deployment topology.

What a Bounded Context Is

The term comes from Eric Evans's 2003 book Domain-Driven Design: Tackling Complexity in the Heart of Software. A bounded context is the boundary inside which a particular model, and the language that describes it, stays consistent. Outside that boundary, the same word can mean something else entirely, and that's fine, because you're no longer inside the model where it was defined.

The canonical example: "Customer" in a sales context means someone who can place an order. "Customer" in a support context means someone with a ticket history and an SLA. Same word, two different models, two different sets of rules about what's valid. A bounded context is where you stop pretending those are the same thing and give each one its own vocabulary, its own invariants, and its own boundary.

That's a modeling concept. It says nothing about how many services you run, how you deploy them, or who's on call for which one. Which is exactly where the diagram goes wrong.

The One-to-One Assumption, and Why It Breaks

The popular shorthand is: one bounded context, one microservice. It's easy to teach, easy to draw, and easy to sell in a slide deck. DDD writer Vlad Khononov put the actual relationship more precisely: "A Microservice is a Bounded Context, but not vice versa. Not every Bounded Context is a Microservice." A bounded context defines the largest boundary inside which a model can stay consistent. A microservice is a deployment decision made inside that boundary, and sometimes below it, not a mirror of it.

Here's the failure mode in practice. A team draws contexts too small, one per entity, and ends up with a dozen services that all have to call each other synchronously to do anything useful. That's not microservices. That's a monolith with the process boundaries moved into the network, which is strictly worse: same coupling, new latency, new failure modes.

The industry has a name for it now: the distributed monolith. It shows up most often when a team splits a system along its existing code layers (controllers, services, repositories) instead of along real domain boundaries, then calls the result "microservices" because there are multiple deployables.

The opposite mistake is just as common and less talked about: drawing one context for the entire domain, then building a single service with DDD vocabulary sprinkled over what is, underneath, still a big ball of mud. You get the ceremony of bounded contexts (aggregates, repositories, a ubiquitous language doc nobody updates) without the actual isolation that makes any of it worth doing.

The honest answer is that a bounded context and a service are two different kinds of boundary, and they only sometimes line up:

One bounded context can span multiple services, when the context is large enough that splitting it makes operational sense (different scaling needs, different release cadence, different team).
Multiple small, tightly related contexts can live inside one service, when splitting them would only add network calls without adding independence.
A context can be split across a synchronous API and an asynchronous event stream, which is not "two contexts," it's one context with two integration surfaces.

Deciding which of these is true for a given part of your domain depends on things a bounded context diagram can't tell you: team size, deployment cadence, scaling profile, and how often the boundary needs to move.

Where a Real Split Came From

I've spent the last year leading the technical direction of a healthcare workforce platform built around two products: a staff scheduling system and a credentialing system. On paper, that's two bounded contexts and, if you followed the popular rule, two services. In practice, the platform runs scheduling, credentialing, and integrations as separate services, and that third one is the interesting part.

Integrations wasn't its own bounded context in the domain sense. It doesn't own a piece of business vocabulary the way scheduling ("shift," "coverage," "swap request") or credentialing ("primary source verification," "expiration," "attestation") do. What it owns is a boundary problem: every external system we talk to (identity providers, document verification vendors, notification services) has its own model, its own failure modes, and its own pace of change, and none of that should leak into the scheduling or credentialing models.

That's the anti-corruption layer pattern from context mapping, given its own service instead of a library everyone imports. Once external integrations lived behind their own boundary, the scheduling and credentialing services stopped needing to know anything about a specific vendor's API shape, retry semantics, or auth flow. They call an internal contract; the integrations service is the only thing that has to change when a vendor changes theirs.

That's a service boundary that exists for operational reasons (isolate volatility, isolate failure, let one team own vendor relationships) layered on top of a modeling boundary that exists for domain reasons (keep "shift" and "verification" from ever meaning two things at once). Stabilizing the platform's architecture meant getting that distinction right, not drawing a cleaner box diagram.

When One Service Should Hold Multiple Contexts

The reverse case matters just as much, and it's the one people are more reluctant to admit out loud: sometimes the right call is to keep two related contexts in the same service, at least for a while.

Two sub-domains that change together, get deployed together, and are owned by the same two-person team don't need a network boundary between them. Splitting them early buys you nothing except a second CI pipeline, a second on-call rotation to staff, and a synchronous call where a function call used to be. The tradeoff to weigh isn't "is this technically a separate context," it's "does separating this reduce coordination cost, or just add infrastructure?"

Signals that it's still too early to split:

The two contexts are always deployed in the same release.
One team owns both, and that's not changing soon.
The only reason for the split is "microservices are the right architecture," not a concrete scaling or ownership problem.

Signals that it's worth the network hop:

The contexts have genuinely different scaling profiles (one is read-heavy and cacheable, the other is write-heavy and transactional).
Different teams need to own them, and shared deployment is actively slowing both down.
One context's failure shouldn't be able to take the other down, and today it can.

None of these are visible on a static bounded-context diagram. They're operational facts about the system you're running right now, and they change over time, which is why context boundaries and service boundaries are allowed to diverge and then re-converge later.

The Seams: Context Mapping Patterns Worth Knowing

Once you accept that contexts and services don't automatically line up, the interesting question becomes: what sits at the seam? DDD's context mapping patterns answer that, and three of them cover most real cases.

Shared kernel is when two contexts agree to share a small, explicitly maintained subset of the model, usually because splitting it would cost more than the coordination overhead of keeping it in sync. It's the pattern to reach for rarely and deliberately, not the default.

Customer/supplier is when one context's team can influence the other's roadmap because they depend on it, and the supplier team treats that dependency as a real constraint on what they ship. This is a people pattern as much as a code pattern: it only works if the supplier team honors it in practice.

Anti-corruption layer is the one that shows up the most in practice, and it's the pattern the integrations service above is built on. A translation boundary sits between two models so that neither one has to bend to accommodate the other. A small TypeScript sketch of the shape:

src/integrations/verification/anti-corruption-layer.ts

// The vendor's shape. We don't control this and it can change without warning.
type VendorVerificationResponse = {
  verification_status_code: "V1" | "V2" | "V3";
  subject_ref: string;
  checked_at_utc: string;
};

// Our domain's shape. This is the only thing Credentialing ever sees.
type PrimarySourceVerification = {
  status: "pending" | "verified" | "failed";
  providerId: string;
  verifiedAt: Date | null;
};

function translate(vendorResponse: VendorVerificationResponse): PrimarySourceVerification {
  const statusMap: Record<VendorVerificationResponse["verification_status_code"], PrimarySourceVerification["status"]> = {
    V1: "pending",
    V2: "verified",
    V3: "failed",
  };

  return {
    status: statusMap[vendorResponse.verification_status_code],
    providerId: vendorResponse.subject_ref,
    verifiedAt: vendorResponse.verification_status_code === "V2" ? new Date(vendorResponse.checked_at_utc) : null,
  };
}

Nothing clever is happening here on purpose. That's the point: the translation function is the entire cost of keeping the vendor's model out of the domain. When the vendor renames a field or adds a fourth status code, this function is the only place that changes.

Finding the Boundaries Before You Build Anything

If you're doing this for the first time, don't start by drawing boxes. Start with event storming: get the people who understand the domain in a room (or a shared board), and map out the significant business events on a timeline, in the language the business uses for them, not the language your database schema uses. Boundaries tend to reveal themselves as clusters: events that trigger each other tightly belong together, and gaps where one cluster hands off to another, often with a change in vocabulary, are your candidate context boundaries.

It's slower than opening a whiteboard and drawing four boxes from memory. It's also the difference between a boundary that reflects how the business actually works and a boundary that reflects how the code happened to be organized when you looked at it.

Where the Boundary Should Have Been

If I were drawing that diagram again for the platform I'm working on now, I wouldn't add a fourth box for "Integrations" as if it were a peer domain concept next to scheduling and credentialing. I'd draw it as what it is: an anti-corruption layer that earned its own deployable because of operational concerns, not because the domain model demanded a third bounded context. The distinction matters, because the next time someone asks "should this be its own service," the domain diagram won't answer the question. The operational tradeoffs will.

Originally published at andriiboyko.com.