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

Abstract Factory

Create families of related objects that must be used together through one factory interface, so the client never names a concrete class and one choice gives it a matched set, at the price of changing every factory when a new kind of product arrives.

A token from one provider, charged at the other

A marketplace takes card payments through two providers: Stripe for its US merchants, Adyen for its European ones. Every payment goes through three pieces of provider-specific code. The card form runs in the buyer's browser and turns the card details into a payment token, an opaque value that only the provider that issued it can use, so the marketplace's servers never see the card number. The charger sends that token to the provider to take the money. The webhook verifier checks the signature on the callbacks the provider sends later, when a payment settles or is disputed.

Each piece was chosen with its own test of the merchant's region: one in the page that renders the form, one in the payment service before it charges, one in the webhook handler. Three files, each deciding the provider on its own. Then the marketplace let a few large European merchants who already had Stripe accounts stay on Stripe, and the rule became "region, unless the merchant has an override". The form page learned the new rule; the payment service did not. For those merchants the browser produced a Stripe token, the payment service handed it to Adyen, and Adyen refused a token it had never issued. Every checkout for those merchants failed until someone traced it to a question answered three times, in three places that had drifted apart.

Choose the provider once, get all three pieces

The three pieces are not independent choices. They form a family: products meant to be used together, all tied to the same provider. Abstract Factory puts the creation of that family behind a single object. A PaymentKit interface declares one creation method per kind of product: createCardForm(), createCharger() and createWebhookVerifier(). Each provider gets a concrete factory that implements it and returns its own products: StripeKit returns a StripeCardForm, a StripeCharger and a StripeWebhookVerifier, and AdyenKit returns the Adyen versions. Checkout uses the products only through their interfaces, CardForm, Charger and WebhookVerifier, so it never names a concrete class.

One kit, one matched set

Checkout holds only a PaymentKit. Each concrete kit creates its own provider's products, and each product implements the interface checkout uses. The webhook verifiers follow the same shape and are left out.

The decision now happens in one place. A single function reads the merchant's region and override and returns that merchant's kit, and the form page, the payment service and the webhook handler all take their pieces from it. A webhook can arrive days after the payment, when the merchant's override may have changed, so its handler asks for the kit of the provider recorded on the payment, not for today's answer. Checkout receives the kit from outside instead of building it, which is Dependency Injection applied to a factory. Tests get a third concrete factory, FakeKit, whose form, charger and verifier work in memory, so the whole checkout flow runs without either provider.

The pattern makes the matched set the easy path, which is less than a proof. Charger.charge(token) does not check where its token came from, so code that took the form from one kit and the charger from another could still mix them. What changed is that nothing has a reason to: every piece of a payment comes from the kit chosen for it, and no second place decides the provider.

A fourth piece costs every kit

A year later the marketplace starts paying its merchants through the same providers, and the payout code needs a PayoutClient from each. That is a new kind of product, so PaymentKit gains createPayoutClient(), and the change reaches every class that implements the interface: StripeKit, AdyenKit and FakeKit each fail to compile until they return a payout client of their own. Three kits, three edits; with one provider per country, many more.

A new family is the cheap direction. A third provider is one new concrete factory with its own products, and no existing kit and no line of checkout changes; only the function that picks a merchant's kit learns the new name. So the pattern fits when families come and go but the set of pieces each family supplies stays stable. When new kinds of product arrive every few weeks, each one breaks every kit, and the interface is fighting you.

That asymmetry is easy to undo by accident. If a team adds a provider by putting a createNorthpayCharger() method on PaymentKit instead of writing a new NorthpayKit, the cheap direction becomes the expensive one: the change breaks every existing implementation, each of which must now provide a method that means nothing to it, and checkout has to know which method to call, which brings back the provider test from the opening.

Thirteen nodes, two families

The Abstract Factory Pattern Challenge allows 13 nodes and asks for a factory interface with a creation method per product type, concrete factories that each produce one consistent family, product interfaces with their concrete products, and a client that depends only on the abstractions. The payment kits fit exactly: the diagram above, plus WebhookVerifier and its two concrete products. Two things make or break the drawing. The client's edges go only to the factory interface and the product interfaces, never to a concrete product. And each concrete factory's "creates" edges stay inside its own family: a StripeKit arrow that reaches an Adyen product is the opening's bug, drawn.

Its neighbours

Factory Method is the smaller tool: one creation step, overridden by subclasses to decide one product. An abstract factory groups several creation methods whose products belong together, and concrete factories often implement each of them as a factory method. When the difficulty is assembling one complex object step by step, not choosing a matched set, that is Builder. An application usually needs only one of each kit, and whether to make that a Singleton or pass one instance in is that article's question.

Practice this