Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Aggregate

A consistency boundary: a cluster of entities and value objects changed together through one root, which enforces the rules that must hold after every change, referenced from outside only by id, and sized so those rules stay inside it without every change contending for it.

€4,180 that nobody approved

A university research office closes the books on a three-year grant of €360,000 and finds the equipment line €4,180 over its allocation. Every purchase on it had been approved. Looking for the cause, the office found three pieces of code that each changed the grant's budget lines. The purchasing screen checked the remaining equipment money before committing a purchase. The travel module, written by another team, checked against the grant total instead of the line. And an admin screen for moving money between lines updated two rows directly, with no check at all. That was the one: a transfer out of equipment, made while purchases were already committed, left the line allocated less than it had promised.

The grant had rules: commitments on a line never exceed its allocation, the allocations add up to the award, and nothing is committed after the grant's end date. Rules that must be true after every change are invariants. Here they lived in two of the three code paths, one of them checking the wrong total, and nothing stopped a fourth piece of code from writing the rows without knowing they existed.

One way in

An Aggregate is a cluster of domain objects that must stay consistent with each other, treated as one unit for every change. One of them is the root: an Entity, and the only member that outside code may hold a reference to or call. Here the root is the Grant. Inside it sit the budget lines, entities whose identity only matters within this grant (line 3 is Equipment), and the amounts, Value Object instances of Money. Outside code no longer updates a line; it asks the grant: grant.commit(lineId, amount, purchaseRequestId), grant.reallocate(fromLine, toLine, amount). The root checks every invariant before it changes anything, and refuses the change that would break one.

The grant aggregate

Lines and amounts are changed only through the grant. The purchase request is a separate aggregate and holds the grant's id, not the grant.

Because every change goes through the root, the whole cluster is loaded and saved as one: there is one way to fetch a grant, with its lines, and one way to store it. That access is a Repository, one per aggregate root. And when building a grant whose allocations already add up to the award takes more than a constructor, a Factory (DDD) does it.

Other aggregates, by id

A purchase request has its own life: drafted by a researcher, quoted, approved, received. It is an aggregate of its own, and it refers to the grant by grantId, not by holding the Grant object. Code that can walk from a request to a live grant object can change the grant in the same breath as the request, and loading a request can drag the grant along with it; the line between the two boundaries is gone. With only an id, changing the grant means loading it through its own repository and asking it, a separate step someone chose.

One aggregate per transaction

Approving a request touches two aggregates: the grant commits the money and the request becomes approved. The default rule is to change one aggregate per transaction. The grant commits the money in its own transaction and records that it did; the request is marked approved in a second transaction, triggered by a Domain Event such as FundsCommitted. For a moment the money is committed and the request still says pending, and the office's screens have to tolerate that. The event has to leave reliably with the grant's commit, or the request waits forever, which is what a Transactional Outbox is for; it can deliver the event twice, so marking the request approved must be safe to repeat. In exchange, each transaction changes one aggregate, the grant's invariants never depend on another aggregate's state, and the two can later live in different databases.

Teams do break the rule on purpose, changing both aggregates in one database transaction and accepting the coupling; if the business can never tolerate the gap, the boundary itself may be wrong. And if a later step can fail after the money is committed (the supplier cancels), releasing the commitment is a compensation, and a process built from such steps is a Saga.

A version on the root

The root's checks run against the copy each request loaded, so two approvals of €6,000 against the same €9,000, saved at the same moment, can both pass. The usual guard is a version number on the root, checked on save, so the second save fails and is retried against the fresh grant; Unit of Work follows that check through a commit, and Transactions & isolation levels names the lost update it prevents. The guard holds only if every change inside the aggregate, a line's commitment included, moves the root's version, one more reason nothing reaches a line except through the root.

Too big, too small

The version check makes the aggregate's size visible. Suppose the office had made the department the aggregate, with every grant inside, because the department has an overall cap on overhead. Now any commitment on any of 40 grants changes the department's version, two unrelated researchers conflict, retries pile up at the end of the financial year, and loading the department to approve a €200 purchase drags in every grant and every line. The same happens on a smaller scale when the grant holds every invoice and receipt from three years of spending: the aggregate grows without limit and so does the cost of loading it.

Go the other way and make each budget line its own aggregate, and the conflicts between different lines disappear along with the rule. reallocate now changes two aggregates, so the allocations add up to the award only if both transactions succeed, and nothing inside either line can check a sum that spans them. With each aggregate changed in its own transaction, a rule that spans them is no longer an invariant the code enforces on every change; it becomes something checked afterwards and repaired, which is a business decision, not a refactoring.

So the boundary goes where the invariants are. Ask which rules must hold the instant a change commits, and put inside the aggregate exactly the state those rules must keep consistent. The grant with its lines and their committed totals passes that test; the invoices, the receipts and the department's overhead cap do not, because the office accepts checking those after the fact. If one invariant forces a large aggregate, ask the business whether it truly has to hold at every instant; sometimes it only has to hold at month end, and that is a different design.

Signs the boundary is leaking

A report job that fixes a line's committed total directly, because it is faster than loading the grant, bypasses the root's checks and the grant's version check, and the overspend comes back at the next close. And if most use cases need several aggregates to change atomically, the boundaries were probably drawn around nouns rather than around rules.

Draw the grant on a Grid

Open the Aggregate & Repository Challenge and build one aggregate from your own domain, or this grant. Put inside the boundary only what an invariant needs, and write the invariants on the Grid next to the root, so the reason for each member is visible. Connect anything outside only to the root, label any edge to another aggregate with the id it holds, and route the follow-up change through a Domain Event instead of a second write. Then remove one member in your head and ask which rule could now break.

Practice this