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

Policy (reactive rule)

A named business rule that reacts to an event: whenever this happens, issue that command. One trigger, one rule, no memory across steps, written so a domain expert can read and correct it.

"Who decided we refund when the teacher cancels?" The new coordinator at a language school asked it in a staff meeting, with two complaints in her hand. Two students had each lost a Portuguese class that week. One had a lesson credit on her account and an offer of a make-up slot. The other had the offer and nothing else.

The developer who went looking found the honest answer: three handlers had decided. A class can be cancelled three ways, by a teacher in her app, by the front desk on the admin screen, and by the nightly timetable import when a room closes. Each way has its own handler, and each ends with the same few lines, credit every enrolled student and offer a make-up slot. The teacher app and the import agree. The admin handler, copied from an older version, credits only when the class is less than 48 hours away, and the second student's class had been cancelled at the front desk five days ahead. So the school's rule depended on which screen someone had used, and nobody could point at the place where it was written.

A rule with a name and an address

The repair starts by separating what happened from what follows. Whichever path cancels a class, Class records it and raises ClassCancelled; Domain Event explains how an event is raised and handed out. The three handlers stop there. What follows moves to one place, written the way the coordinator would say it: whenever ClassCancelled, then credit each enrolled student one lesson.

That is a Policy, or reactive rule: a business rule made into a named participant, with an event coming in and a command going out. It subscribes to the event, decides whether the rule applies, and issues CreditStudent, once per enrolled student. Offering the slot is a second policy on the same event, because it is a second rule: the school may well change one without the other.

One event, two rules

Each policy knows when something should happen. The handlers behind them know how.

Why not put the rule on Class, which already knows it was cancelled? Then Class has to know about credits and slots, every new reaction means editing it, and a failure in billing can stop a class being cancelled. Why not in the handlers that take the cancellations? That is how the school got three copies: each of them runs on its own path only. Application Service (DDD) orchestrates one use case, and this rule has to hold across all three. The handlers behind the policies are still needed, and the split is the point: CreditStudent knows how a credit is applied, and the policy only knows when. A policy that starts applying credits itself has taken over the handler's job.

The price of delivering the event through a broker, as the school now does, is that the cancellation and the credit are no longer one transaction: the credit appears a moment later, or much later if the policy's subscriber is down, so somebody has to watch for that. And a broker can deliver the event twice, so CreditStudent has to be safe to receive twice, keyed on the class and the student, as Idempotent Consumer explains.

The rule that starts remembering

Next the coordinator asked for this: once every student in a class has answered the offer, or two days have passed, tell the teacher how many are coming. It sounds like one more line, but a policy has nowhere to keep track. Each time it fires, it sees one event and then forgets it. It could count the stored answers as each one arrives, but a student who never replies sends no event, so something has to follow each class across many events up to that deadline. Looking up the enrolled students is fine, since that is reading data to decide, not remembering; but delivery can lag, so read them as of the cancellation or have the event carry them. If the reactions depend on remembering what already happened across steps, that is a Process Manager.

The opposite drift is quieter. A StudentPolicies class reacts to ClassCancelled, StudentEnrolled and PaymentFailed and fires five different commands, because they all concern students. Changing one reaction now means reading the other four, and the coordinator can no longer tell which rule is which. Split it into one policy per rule: one trigger event and the command(s) it leads to.

When one policy feeds another

Policies chain, since a command causes a new event that can trigger the next policy, and if the chain closes into a cycle, nothing in it stops. Say the school drafts two more rules: whenever ClassCancelled, open a make-up class that week for the same students; whenever MakeUpClassOpened and no teacher is free, cancel it. In a holiday week with no teachers free:

  1. The front desk cancels Thursday's class, and ClassCancelled goes out.
  2. The credit policy credits the eight students, and the make-up policy opens a class.
  3. The staffing policy finds no teacher and cancels that class, so ClassCancelled goes out again.
  4. The credit policy credits the eight students again, and the make-up policy opens another class.

Every pass has a new class id, so the key that made CreditStudent safe does not catch it: each credit looks legitimate. Left running overnight, it can leave each student with thousands of lessons in credit. Neither rule is wrong alone, and a test of either rule passes. The way to see it is to read the rules as a graph, event to policy to command to event, and look for a cycle. Where one exists, make sure it ends: here, a make-up class that gets cancelled does not earn another make-up class. As a backstop, each message can carry how many reactions led to it, so a chain past some depth stops and alerts someone. A long chain has a second cost even when it ends, since no single place shows the whole flow; Choreography weighs that trade-off.

The list on the coordinator's desk

In EventStorming, the workshop where developers and domain experts map a process on a wall, these rules are the "whenever…" stickies placed between an event and the command it leads to. That wall is the argument for the pattern: a coordinator will not review a handler, but she will review a sentence. The school's rules now fit on half a page, each line matching one policy and one test:

  • Whenever ClassCancelled by the school, credit each enrolled student one lesson.
  • Whenever ClassCancelled by the school, offer each enrolled student a make-up slot.
  • Whenever MakeUpSlotAccepted, spend one credit and enrol the student.

She read it once and corrected it: classes cancelled for a public holiday earn no credit, because the term fee already leaves holidays out. The first line became "Whenever ClassCancelled by the school, except for a public holiday, credit each enrolled student one lesson." That took one changed line, one changed policy and its test, and the 48-hour condition was gone with the handler that held it.

The nearest practice is the Saga Challenge, whose palette has no Policy node but which asks you to "Show the saga reacting to events and dispatching the next command", the same event-in, command-out shape with a stateful saga doing the reacting. Write a whenever/then sentence on each of those edges, then mark the ones that need the saga's memory and the ones a Policy could do alone.

Practice this