Structural Patterns

Warning signs: it mirrors the subsystem method-for-method, it keeps growing into a god-object, it leaks internal types in its signatures, or nobody uses it because callers still import internals. Fix by resizing, splitting, or deleting it.

The factory keeps a map from the shared-state key to the single instance, creating one only on a miss. It must be thread-safe, must not let two callers get two different instances for the same key, and must have a bounding or eviction policy so the map does not grow forever.

It pays off when you have very many objects but few distinct values, the duplicated part is big enough to matter, and the objects are long-lived. Reject it when values are mostly unique, the objects are few or short-lived, or the API damage outweighs the memory saved.

The framework returns a generated stand-in instead of your object: either a class implementing your interfaces, or a subclass of your class, that runs extra logic then delegates. Limitations: only calls that go through the returned reference are intercepted, so internal self-calls, final/private/static methods, and direct field access are not.

A protection proxy controls who may call — it checks the caller's rights and forwards or denies. A remote proxy controls where the object is — it hides that the real object lives in another process or machine. The first can be bypassed if callers reach the subject directly; the second hides latency and partial failure.

Bridge splits one concept into two hierarchies — what it does and how it is done — connected by composition, so you can extend either side without multiplying classes. Adapter reconciles two interfaces that already exist and clash; Bridge is designed up front. Strategy swaps one algorithm, not a whole implementation hierarchy.

At architecture scale, a facade becomes a module's or service's single published entry point. Everything behind it can change freely; everything the facade exposes becomes a contract you must version, deprecate and support.

The same intents scale up: an API gateway or service facade simplifies a subsystem, RPC client stubs and sidecars are proxies, anti-corruption layers are adapters, and middleware chains are decorators. Each layer buys decoupling but costs latency, one more hop to debug, and a contract someone must own.

None of those are required. A facade can be several classes, hold state, and be created per use. For tests, clients now stub one facade instead of many collaborators, which makes their tests shorter — but the facade itself still needs integration tests.

Bridge adds indirection and a second hierarchy to navigate, and forces you to design the interface between them early. It goes wrong when the interface mirrors the abstraction, leaks implementation details, or exists with only one implementation.

Flyweight saves memory by sharing one object across many logical occurrences. The shared part (intrinsic state) is context-independent and immutable, such as a character's glyph shape; the varying part (extrinsic state) such as position or colour is passed in by the caller instead of stored per instance.

At system scale the target interface becomes a "port" your domain owns, and each external system gets an adapter that translates its model into yours. This keeps vendor concepts out of the core, at the cost of extra layers and mapping code.

The same idea scales up: a stable interface between a domain core and swappable technical mechanisms — ports and adapters, driver/plugin interfaces, storage or messaging abstractions. It succeeds when the seam is narrow, primitive and rarely changed.

Composite fits only genuine part-whole hierarchies where nodes really share behaviour. It goes wrong when leaves differ too much to share a meaningful interface, when the tree is loaded lazily from a database (one query per node), or when depth comes from untrusted input and overflows the stack.

Skip decorators when the behavior applies uniformly to many types (use a middleware pipeline or framework interceptors), when there is only one fixed variation (put it in the class), or when the interface is too large or not designed for wrapping.

Because one object is shared everywhere, any mutation of it affects every user; comparing by reference works until an instance is created outside the factory or evicted; locking on a shared instance can make unrelated code contend or deadlock; and copies from serialization or other tenants silently break the "one instance" assumption.

The same idea scales up: API gateways, reverse proxies, service-mesh sidecars, caching layers, and database connection proxies all stand in front of something and control access to it. It's the wrong call when it adds a hop and an operating cost without policy — pure pass-through indirection.