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

Content-Based Router

One component reads each message and sends it to exactly one destination chosen from its content, so the routing rules live in one place instead of in every sender, and that one place has to know every destination.

Three lines from the intake log

This is what the support system recorded for one ticket on a Tuesday morning:

  1. 08:14 Ticket 48213 arrives by email: written in Spanish, about the Ledger product, from a customer on the Enterprise plan.
  2. 08:14 Intake assigns it to the Ledger queue, worked by an English-speaking team.
  3. 11:52 A team lead reassigns it by hand to the Enterprise desk, whose contract promises a first reply within one hour.

Nobody broke a rule that morning. The email intake sent anything about Ledger to the Ledger queue. The web form had its own rules and checked the customer's plan first. The chat widget routed by language alone. Each way in decided where its tickets went, each was written by a different team, and the Enterprise rule existed only in the web form. This customer had sent an email.

One place that reads the ticket and decides

The fix takes that decision away from the senders and gives it to a single component, a Content-Based Router. Email, form and chat all put their tickets on one intake channel. The router reads each ticket and forwards it to exactly one destination, chosen from what the ticket says: its product, its language, its customer's plan. The senders no longer know which teams exist or how they are organised, and the question "where does a Spanish Enterprise ticket about Ledger go?" has one answer, written in one component.

Route by plan, language and product

Each ticket leaves the router on exactly one edge. The rules are checked in the order of their numbers and the first match wins; a ticket no rule matches takes the default route to triage.

TipKeep the routing rules in the router, not in the producers: a rule hard-coded in each producer means every producer changes when a route does.

One ticket, three matching rules

Ticket 48213 matches three rules at once: its plan, its language and its product each point somewhere. A router that delivers to exactly one destination has to pick, and in many implementations the pick comes from the order of the rules: they are checked from the top, and the first one that matches wins. The order is a business decision written as code. Putting the Enterprise rule first says the one-hour promise matters more than answering in the customer's language; putting the language rule first says the opposite. Either can be right. What goes wrong is an order nobody chose, such as the order in which the rules happened to be added.

Overlaps are easy to create without noticing, because two rules are usually written months apart by different people. A cheap guard is a set of sample tickets, each with the destination it should reach, run against every change to the rules. Have the test report every rule that matched each sample, not only the winner, and the overlaps show up in review instead of in a customer's inbox.

If the Ledger team also wants every Enterprise ticket about Ledger, bending this router into sending two copies breaks its one promise; a message that goes to a computed set of destinations needs a Recipient List. Out-of-office auto-replies that bounce back into intake should go nowhere at all; a Message Filter, a router with a single way out, drops them.

The ticket no rule matches

In March the company launches a product called Atlas. Its first tickets come in English, from customers on the Starter plan, about a product no rule mentions. Not Enterprise, not Spanish, not Ledger. Where do they go?

If the router simply has no branch for this case, the outcome depends on how it was written. It might throw, and intake retries the same ticket again and again. It might log a warning and acknowledge the ticket, and the ticket disappears with a customer still waiting. So the last rule matches everything: a default route, here to a triage queue that a person works through, assigning each ticket by hand. Triage also measures the rules. When it fills with Atlas tickets, a rule is missing, and an alert on its depth or on its rate against the usual level can say so before customers do.

Keep the default for tickets the router could read but not place. A ticket it cannot read at all, such as an email whose body failed to parse, belongs on an Invalid Message Channel, where someone can find out why it could not be read. A ticket placed correctly whose destination then keeps failing to process it belongs on a Dead Letter Channel once its retries run out. Three outcomes in three places, so the people working triage are not reading parser errors.

Rules that read only the ticket

The email intake knows the sender's address, not the customer's plan. A router that looks the plan up in the billing system for every ticket depends on that system being up and fast, and its rules can no longer be tested against a recorded ticket alone. Adding the plan to the ticket in a step before the router, a Content Enricher, lets the router decide from the message alone.

The price of a single place

The cost of centralising the rules shows up the day the company opens a Japanese desk. The router has to change: a new destination, a new rule, and a decision about where in the order it goes. Because the router knows every destination, every new team, renamed queue or retired product means changing it, and deploying it when the rules live in code, and its owners become the team everyone else waits for. The senders stopped knowing the topology; the router now knows all of it.

That is usually a good trade when destinations change less often than senders, as support teams do. When destinations come and go every week, one way out keeps the single place but turns the rules into data the router loads, a table support managers can edit, with the sample-ticket test run before each edit takes effect. The other lets each destination ask a shared channel for what it wants, the way a Selective Consumer does, which removes the router, its rule order, and the one place where all the rules can be read together: when two selectors overlap, on a queue the matching consumers compete for the ticket and the broker decides which one gets it, and on a topic each matching subscription gets a copy.

Ticket 48213 on a Grid

The Content-Based Router Challenge asks for this design, every message reaching exactly one destination and the rules living in the router. Draw the client, the intake channel and the router, then an Enterprise channel and a Spanish channel, each with its desk, and a triage channel for the default route. Number the router's edges in the order its rules are checked, label the last one as the default, and keep every rule on the router's side, so that a Japanese desk would be one more edge from the router and no change to the client.

Practice this