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

Mediator

Centralize how a set of objects interact so they don't reference each other directly, and keep the hub that holds the rules from growing into the next tangle.

Music over the caller

The note from the test drive was two lines long. Halfway through a phone call, the navigation said "In 300 metres, turn right", and when it finished, the music came back on, over the caller's voice.

The car's infotainment software has four modules that make sound: the music player, the phone, the navigation voice and the parking sensor's beeps. Each pair that has to agree on who is heard had a rule, and each rule lived in one of the two modules. The phone paused the music when a call started. The navigation voice lowered the music's volume before speaking and afterwards restored normal playback: full volume, and playing. The parking sensor lowered everything else. Every rule was right on its own. This bug came from two of them meeting: the navigation voice's "restore" pressed play on music the phone had paused, because nothing in the navigation module knew a call was in progress.

Six pairs, each with its own rule

The obvious fix was one more check, phone.isInCall(), inside the navigation module. That is one more reference between two modules that should not need each other. Four modules can form six pairs, and once most of them have a rule, every module imports most of the others. Adding a fifth source of sound, a voice assistant, raises the possible pairs to ten and means editing every module that has to give way to it. No single file says what happens when the phone rings while the car is reversing. The answer is spread across three classes and depends on which one ran first.

Every module knows the others

Each line is a direct reference and a rule that lives in one of its two ends.

One object that knows the rules

Mediator replaces that web of direct references with a hub. The modules, called colleagues in the pattern, stop referencing each other. Each holds a reference to one object, the mediator, and tells it what happened: the phone reports that a call started, the navigation voice that it has something to say. The mediator knows every colleague and decides what each one does next. Colleagues talk to the mediator, which coordinates them, turning many-to-many coupling into one-to-many.

Colleagues talk through the Mediator

Each module references only the audio focus object, which holds every rule about who is heard.

In the car it is an audio focus object. Replay the test drive through it:

  1. The phone tells the mediator that a call has started.
  2. The mediator notes that music was playing, pauses the music and switches navigation prompts to screen-only.
  3. The navigation voice asks to speak, and the mediator shows the turn on screen instead.
  4. The phone tells the mediator that the call has ended.
  5. The mediator resumes the music, because it was playing before the call, and gives the navigation voice its sound back.

The bug is now one rule in one place: music resumes only if it was playing when the first interruption began, nothing that outranks it still holds the sound, and the user has not stopped playback in the meantime. The voice assistant becomes a fifth colleague plus a few lines in the mediator, and the other four modules do not change. The rules can be tested together too, by driving the mediator with fake colleagues and checking what it tells each one.

Why not let them just listen to each other?

Wiring the four modules with Observer looks like a lighter answer: the phone announces "call started", the music player and the navigation voice subscribe and react. But a subject knows its listeners only through the observer interface, and decides nothing about what they do. The decisions stay in the listeners. The music player has to know which announcements should pause it, the navigation voice which should silence it, and unless other code does the wiring, each still needs to know which other modules exist in order to subscribe to them. The pairwise knowledge has moved into subscriptions, and the music-over-the-caller bug can happen exactly as before.

A mediator is the opposite arrangement: it knows its colleagues by name and decides for them. The two are often combined. Colleagues can be subjects with the mediator subscribed to each of them, so Observer carries the news to the hub and the mediator decides what happens next. Observer is the wiring; the mediator is where the rules live.

When the hub becomes the tangle

A year later the audio focus object was 1,400 lines long. It still ranked the sources, but it also picked volume curves for each speaker, laid out the screen when the reversing camera came on, reconnected Bluetooth phones and wrote the diagnostics log. Every feature touched it, and two teams editing it at once was a weekly merge conflict. The coupling the pattern removed from the colleagues had collected in the hub instead, now as a god object: one class that knows and does too much.

Two habits keep it in check. The mediator decides when and whether; the colleagues keep how. Lowering the volume smoothly is the music player's job, and the mediator only says "duck". And rules that never interact can live in separate mediators: laying out the screen when the camera comes on does not depend on who is heard, so it can live in a different object.

Watch outLetting colleagues keep a few "convenient" direct references to each other alongside the mediator quietly rebuilds the many-to-many coupling it was meant to remove, and the rule that uses that reference is invisible to anyone reading the mediator.

Facade also puts one object in front of several, but its calls run one way: outside code calls the facade, and the classes behind it do not know it exists. A mediator's colleagues know it, call it, and are called by it.

A fifth colleague

In the Mediator Pattern Challenge, pick your own set of colleagues and put one mediator among them, named after what it coordinates, the way Audio focus names its job. Read the result by its edges: none should join two colleagues directly. Then repeat the voice-assistant test from the car: add a fifth colleague and count the existing nodes that gain an edge. With a mediator in place, the answer is one.

Practice this