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

Command

How turning a request into an object lets an app queue, log and undo it, and what undo must keep when an operation has no exact inverse.

Can we put the old prices back?

The merchandiser at a homeware shop meant to take 40% off 38 table lamps. She picked Lighting instead of Table lamps in the admin's category menu, clicked Apply, and 412 products went on sale. Ten minutes later she asked the developers the obvious question: can we put the old prices back?

The Apply button's click handler did the work itself: it loaded every product in the category, multiplied each price by 0.6, rounded to the cent and saved. Once it returned, nothing remembered what had been asked, by whom, or what the prices had been. The first idea was to run the opposite and divide every price by 0.6. A lamp at €11.99 had become €7.19, and €7.19 divided by 0.6 is €11.983, which rounds to €11.98. Rounding had thrown away a fraction of a cent that no division recovers. Some products had also stopped at their minimum price, a floor the discount never goes below, and dividing a floor by 0.6 gives a price nobody ever set. In the end the team restored the previous night's backup, and lost the morning's other price edits with it.

The click becomes an object

Command packages a request (the receiver that will do the work, the action, and its arguments) into an object. In the rebuilt admin, Apply no longer touches prices. It builds a DiscountCategory command holding the catalog service, the category Lighting and the rate of 40%, and calls its execute(). Because the request is now data, it can be queued, logged, retried or undone.

The pattern names three roles. The Invoker triggers a command without knowing what it does: here the Apply button, which sees only execute(). The Receiver does the actual work, here the catalog service. The command sits between them, and every command implements the same small interface: execute() and, when it can be reversed, undo().

Two invokers, one command

The button and the scheduler both call execute() and never touch the catalog. The command saves each price before lowering it, and those saved prices are what its undo() writes back.

Once a request is data

  • Queue it. The real spring sale starts on Friday, so the merchandiser builds the command on Monday and the admin hands it to a scheduler, a second invoker that calls the same execute() on Friday.
  • Log it. Every executed command writes one line: who ran it, which category, which rate, when. "Who discounted Lighting?" becomes a lookup, in the merchandiser's terms instead of 412 row updates.
  • Retry it. If the catalog service times out halfway, the admin can run the command again. That is safe only if running it twice gives the same result. "Set these 412 products to these prices" does; "take 40% off" does not, because a second run takes 40% off the prices the first run already lowered, so a retryable discount works out its products and new prices once, before its first write; Idempotency & exactly-once illusions covers the rest.

What undo has to keep

The admin keeps a history, a stack of executed commands. Undo takes the last one off the stack and calls its undo(). Redo runs a command that was just undone again, and running a new command usually clears the redo list, because those commands were undone from a state the new command has since changed.

What undo() needs depends on the operation. Some operations have an exact inverse: if the banner command only runs while the homepage banner is hidden, showing it is undone by hiding it, and the command stores nothing extra. The discount has none, as the €11.98 lamp showed: rounding and the minimum price throw away information the inverse would need. So the discount command stores the state needed to restore: before it changes anything, it records each product's price, and undo() writes those prices back. When the saved state is an object's internals, captured without exposing them to whatever holds the history, the technique is Memento.

Writing old values back has its own trap. Between the discount and the Undo, a colleague set one floor lamp to €89. An undo() that blindly writes the saved price erases her edit, which is the backup's mistake on a smaller scale. So the command also stores the version each product had right after the discount's write, and undo() restores a price only through a conditional write that succeeds if that version is still current. A product whose version has moved, even if a colleague later set the price back to the discounted one, is left as it is and listed for the merchandiser, and the history records the undo as partial, with the products it restored and those it left.

What a command cannot take back

The discount had one more effect. The shop emails customers when an item on their wishlist drops in price, and 2,000 of those emails went out within a minute. No undo() reaches into an inbox. When a command's effects leave the system (an email, a payment, an order sent to a supplier), the most you can do is follow it with another action that makes amends, such as a correction email; that is a Compensating Action, not an undo. An honest history says so before the click: undoing this discount restores the prices and leaves the emails sent.

Replaying the logged commands on an old backup rebuilds the catalog only if the log holds every change made since that backup, in order, the replay starts from the same state, every command gives the same result from that state (none reads the clock or the day's exchange rate), and effects that leave the system are switched off. Otherwise the replay computes different prices, or sends the 2,000 emails again.

A request, not a fact

A command is a request, and a request can be refused: the rebuilt catalog service may refuse, instead of clamping, a discount that would take a product below its minimum price. An event such as PricesDiscounted is a fact that already happened and cannot be refused; Domain Event is about naming and using those facts.

The word has two other common homes, both built on the same idea of a request as data: a message handled by a command handler in CQRS, and the object a button is bound to, with its check of whether it can run now, in MVVM: Model, View, ViewModel.

When it costs more than it gives

Every action becomes its own command, usually a class with a constructor, execute(), often undo(), and the state undo needs. On a settings screen where nothing is queued, logged or undone, that is ceremony, and a direct call is the better design.

Watch outOnce an app has a history, the expensive mistake is the shortcut: letting an Invoker call the Receiver directly for a "simple" case, such as a quick button that rounds every price to .99. That call never reaches the log or the history: nobody can tell who ran it or undo it, and the next Undo of the discount underneath it finds hundreds of prices it did not set.

Sketching the admin in the Challenge

The Command Pattern Challenge gives you eight nodes for the roles above: a Command interface, which is the Port / Interface node, concrete commands, an Invoker that holds them and a Receiver that does the work, drawn so that undo has somewhere to come from. Before you submit, follow the Invoker's arrows: if one reaches the Receiver directly, you have drawn the shortcut from the warning above. Then decide where undo's data lives, with a Memento beside the discount for the prices it replaced and nothing beside the banner, whose inverse needs nothing stored. The drawing works when the discount could be undone or replayed from what its command holds alone.

Practice this