Architecture, tested against what actually shipped.
Ten concepts are each explained from their canonical source: Meyer, Fowler, the Gang of Four, Nygard, Richardson, and the W3C. Each concept is then checked against a real eleven-service distributed estate to see how far the implementation actually got.
Most architectural documentation stops at the definition. However, practical engineering exists in the gap between a theoretical pattern and the actual code. Each page in this section defines the strict pattern requirements. Next, it identifies exactly where the production system differed.
How to read this
Verified
The page describes something that existed in the codebase, with the structural evidence that settles it. Claims are bounded, not inflated.
Prescriptive
The pattern was absent from the estate. These pages are “what to do next”, and say so plainly rather than implying credit.
The gap
Every page names what the canonical definition requires that the common implementation omits. That gap is the actual lesson.
Hard lessons
6 conceptsPatterns that were reached for and half-landed. Each of these was measured in a real codebase, and in every case the dir structure claimed more than the implementation delivered. This discrepancy is the most common way these patterns fail.
CQRS vs CQS
Two packages named command/ and query/, one JPA entity behind both. Three mechanical tests separate genuine CQRS from an organisational split, plus Fowler’s own caution about when not to reach for it.
Message Brokers vs Event Buses
Redis pub/sub is fire-and-forget: no persistence, no replay, no consumer groups. What at-most-once really costs, and what a team had to hand-build above it to get delivery guarantees back.
Read HARD LESSON 03Strict Smart/Dumb Components
Presentational components that import a global store lose their presentational nature. Composables often introduce a hidden state leak into these components, a structural flaw that prompted the pattern’s original author to revise his recommendation.
Read HARD LESSON 04Strategy Pattern & Dependency Inversion
A Context holding concrete types is not Strategy, and an interface beside its only implementation is indirection, not inversion. One service contained a textbook-perfect instance and a broken one, 200 lines apart.
Read HARD LESSON 05Compile-time vs Runtime DTO Mapping
Reflection-based mapping turns a renamed field into a production incident; annotation processing turns it into a build error. Plus why reusing one DTO for request and response guarantees churn.
Read HARD LESSON 06Defense in Depth
UI permission filtering is a usability affordance, never a security control. Where authorization has to live, how to enforce it at the API boundary, and how to constrain the presentation layer safely.
ReadDistributed systems essentials
4 conceptsPatterns the estate did not have. Each concept answers a problem the pages above prove the system had. These are prescriptive: what to build next, and what it costs.
API Gateway & Backends-For-Frontends
When eleven services each expose their own base URL to the browser, the client becomes the integration layer. What a gateway centralises, and where Sam Newman draws the line at one BFF per experience.
Read ESSENTIAL 02Circuit Breakers
Sixteen hardcoded service-to-service calls with no timeout policy is a cascade waiting for its first slow dependency. Closed, open, half-open, and why the timeout matters more than the breaker.
Read ESSENTIAL 03The Outbox Pattern
The dual-write problem: you cannot atomically commit a database transaction and publish an event. The outbox makes the publish part of the transaction, and a relay does the rest.
Read ESSENTIAL 04Distributed Tracing & Correlation IDs
A correlation ID in the MDC is not distributed tracing. The difference between stitching logs together and reconstructing a causal span tree, plus the W3C header that makes it portable.
Read