design-patterns

Use when external system types, vocabulary, or conventions bleed into your domain model, a single provider change would require touching many internal files, or a legacy system must keep running while a new one is built alongside it. Apply before writing any integration with an external API, legacy codebase, or third-party service. Covers Anti-Corruption Layer, Gateway, Facade, and Strangler Fig.

Use when behaviour varies across cases, accumulates conditionals, or needs to be decoupled, queued, undone, or observed. Apply when a method is growing if/switch branches, an algorithm differs per context, a pipeline needs flexible steps, or objects need to react to each other without tight coupling. Covers all 10 GoF behavioural patterns.

Use when read and write performance requirements diverge significantly, complex reporting is painful through the domain model, or you need to scale reads and writes independently. Apply before splitting any command/query handler or building read-optimised projections. Covers Command Query Responsibility Segregation — including when it is overkill — with guidance on applying only as much separation as the problem demands.

Use when object creation is the source of pain — constructors growing too complex, the same setup repeated, unclear which concrete type to instantiate, or a shared instance causing hidden coupling. Apply before writing any factory, builder, or instantiation logic. Covers all 5 GoF creational patterns: Singleton, Builder, Factory Method, Abstract Factory, Prototype.

Use when persistence logic bleeds into domain or business code, tests require a real database to verify business logic, ORM types appear in service or handler code, or switching storage would require touching domain classes. Apply before writing any database query, repository, or ORM integration. Covers Repository, Unit of Work, Data Mapper, and Active Record with explicit guidance on when each applies.