Ports and Adapters, Explained With One Checkout
Hexagonal architecture in plain words: what Cockburn meant by ports and adapters, the one dependency rule behind it, and how much of it your codebase really needs.
Blog series
A practical path through code boundaries, dependency direction, distributed systems, resilience, data, and the trade-offs that appear as software grows.
Hexagonal architecture in plain words: what Cockburn meant by ports and adapters, the one dependency rule behind it, and how much of it your codebase really needs.
Hexagonal, Onion and Clean Architecture share one rule: dependencies point inward. What each one adds, how their terms map, and how much your team needs.
DI is one small move: stop letting a class build its own dependencies and hand them in. Constructor injection, the composition root, containers and the usual traps.
Your top-level folders decide how many places one change touches. When layer-first is fine, when feature or domain folders win, and how to keep boundaries honest.
Most teams should start with a monolith, enforce module boundaries next, and split out services only when team or scaling pain is real. Here's how to tell.
Micro-frontends let each team ship its own slice of the UI. How the pieces get stitched together, what it really costs to run, and when a tidy monorepo is enough.
When to call a service and when to publish an event, what brokers really guarantee, how to survive duplicate messages, and when events only add complexity.
When services stop sharing a database, you lose JOINs and cross-service transactions. Here's who should own what, and which pattern fills each gap.
A call that leaves your process can hang, fail or run twice. How timeouts, jittered retries, idempotency keys and circuit breakers stop that failure from spreading.