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

Facade

Give the clients of a subsystem one smaller interface that knows which parts to call and in what order, without taking direct access away from the code that needs it.

Which one do I call first?

That was the whole of the question in the team channel. A developer new to a podcast-hosting platform had been asked to add a publish endpoint to the partner API, so that podcast networks could release episodes from their own tools. In the codebase she found five services that each did part of the job. AudioStore keeps the uploaded master file. LoudnessCheck measures the mix against the platform's target level. Transcoder makes the 64 and 128 kbit/s files that listeners download. FeedWriter adds the episode to the show's RSS feed, and CdnCache purges the CDN's cached copy of that feed, so that the CDN fetches the feed again instead of serving the old one.

Nobody answered with a document, because there was none. So she guessed an order that looked natural: store the file, check loudness, transcode, clear the feed's cache, then write the new feed. Clearing a cache before writing is a common reflex. On staging, which has no CDN in front of the feed, every test passed.

Five calls, and the order matters

The first network to use the endpoint released its launch episode at 9:00, the minute its newsletter went out. Podcast apps showed the episode a little after 15:00. The purge had run before the feed write, the first app to ask for the feed in between had put the old version back in the CDN's cache, and the CDN served that copy until it expired, six hours later on this platform. The purge has to come after the feed write. That order closes the gap this incident fell into.

It is not the only rule. Loudness is measured on the master, before transcoding, so a mix that fails the check is rejected instead of published at the wrong level. The feed must not list an episode before its files exist, or an app that refreshes in that gap gets a link that returns 404. None of this was written in the five services. It was written in the dashboard's Publish button, whose handler called them in the right order, and every new client had to dig it out of that code or guess.

One call that knows the order

The fix moved the sequence out of the clients into a class named EpisodePublisher, with two methods: publish(draft) and unpublish(episodeId). publish calls the five services in the right order with the right arguments, the button calls it instead of the services, and the partner endpoint became a few lines that check the request and call it.

Pulling the order out of the button gave the subsystem a Facade, one simpler entry point over a subsystem of several parts. The five services are unchanged, still do all the work, and do not know the facade exists. What the facade holds is what each client used to need to know: which parts take part, in what order, with which arguments. Its interface is new and smaller than the five it covers together, shaped around what callers want done rather than how the parts do it, where an Adapter converts an existing interface into one a client already expects.

One door, many rooms

Both clients call publish(), and only the facade knows the five steps and their order. The loudness report calls LoudnessCheck directly, by choice.

The door is not locked

A few months later the audio team wanted a number: how many of the 40,000 episodes in the back catalogue would fail a new, stricter loudness target? That job needs LoudnessCheck and nothing else. It publishes nothing, writes no feed and purges no cache. Sending it through EpisodePublisher would mean adding a method to the facade that has nothing to do with publishing, so the report calls LoudnessCheck directly, and that is fine. A facade does not forbid direct access to the subsystem. It is a shortcut for the clients that want the common path, and code that needs finer control, or a part the facade does not offer, may still use the parts.

Watch outCommon mistake: when the facade is meant to be the boundary for an operation, letting a client reach past it straight into a subsystem part for "just this one case" brings back the coupling the facade was meant to hide, and with it the order. A tool that releases one episode early by writing to FeedWriter itself skips the purge, so the CDN can keep serving the old feed for up to six hours: the launch-day bug again, for the one episode someone was in a hurry to release. A facade on its own does not stop that call, so make the boundary an explicit choice, not an accident: here, a review rule that nothing outside EpisodePublisher writes to the feed or purges it.

What a facade should not take on

publish runs five steps against five services, and any of them can fail. The facade does not make them atomic. If the feed write fails after the files are stored and transcoded, nothing is undone by itself. What the facade changes is that there is one place to decide what happens next: here, the episode stays a draft, its files are kept, and the caller is told which step failed.

The other risk is growth. Every new feature that touches episodes looks like a candidate for one more method on EpisodePublisher, and a facade with forty unrelated methods is the old tangle moved into one class. When another group of clients wants its own simple view of the same parts, such as an analytics page that only needs download counts, give it a second facade. Keep the subsystem's rules in the subsystem, too: which loudness target applies is for LoudnessCheck to decide, and the facade only calls it. And keep the calls one way. If the parts start calling each other through the facade to coordinate as peers, it has become a Mediator, which is a different pattern with a different job.

Drawing the publisher

The Facade Pattern Challenge allows eight nodes, which fits this subsystem exactly: two Actor nodes for the Publish button and the partner API, one Facade, and five Service or Module nodes for the parts, or a subsystem of your own of the same size. The Challenge asks for clients that depend only on the facade, so treat it as the boundary of the publish path and leave the loudness report out. Every client edge ends at the facade and carries the name of its method; none reaches a part, and none names a step such as the feed write or the purge. Then put the launch-day question to your drawing: where would a new client learn the order of the steps? If the answer is anywhere but inside the facade, the next new hire will have to guess it again.

Practice this