Architecture
Designing systems that stay simple to change as the product grows.
Building a program: the questions AI can't settle for you
Subdomains, bounded contexts, architecture, data, scale, security, prod: the questions to ask when you build a program, which AI alone cannot settle.
Have an AI analyse your bounded contexts
Relationships, changes, language, maintenance: AI sub-agents analysing your bounded contexts can surface deep design problems before they cost you weeks.
Bounded contexts: why designing them well matters
Well-designed bounded contexts protect your models' language, ease organisational constraints and, through the context map, guide your technical choices.
Subdomains vs bounded contexts: the problem and the solution
In DDD, subdomains and bounded contexts are often confused. The first exist in the business; the second are designed to organise the software solution.
The outbox pattern: consistency outside the aggregate
An aggregate keeps one business unit consistent. For what lies outside, like emailing the invoice, the outbox pattern guarantees it eventually happens.
The DDD aggregate: a consistency boundary for your invariants
In tactical DDD, an aggregate groups related objects behind a single root so your invariants always hold, including at the moment they are persisted.
Core, supporting, generic: the three kinds of subdomains
Analysing the business domain reveals three kinds of subdomains: core, supporting and generic. Mapping them tells you where to spend your time and effort.
Worn out by the pace of AI? Go back to the fundamentals
Releases, workflows, tools: with AI, every developer now feels the fatigue JS developers know well. My remedy: the fundamentals, stable and lasting.
The Result Pattern: telling bugs from business errors
Your cancelOrder() can fail in many predictable ways. The Result Pattern separates the business error you return from the bug that goes to Sentry.
Software architecture and craftsmanship in the AI era
Transaction Script, DDD, Clean Architecture, CQRS, TDD, SOLID, Big Ball of Mud: working on software architecture has never been more useful or accessible.
Maintenance effort = Integration strength × Distance × Volatility
Vlad Khononov's formula from DDD Europe: maintenance effort is strength times distance times volatility, and zeroing just one dimension collapses it.
A good AI harness lets you use much cheaper models
On a codebase with broken import rules, Opus fixes it alone, Haiku falls for it, until an ESLint rule corrects it for 4 to 5 times less money.
Where the value of a tech project really lives
Business rules, not technology, hold 80% of a tech project's value. Yet most projects start with code choices or the first screens instead.
ADRs give AI agents the history your code can't tell
README, CLAUDE.md and AGENTS.md only describe the current state of the code. ADRs add the missing history: why that decision, which alternatives were ruled out.
The first week without writing a line of code
On any project, greenfield or brownfield, leave the keyboard alone the first week: understand, challenge the architecture, model the business.
The boy scout rule: clean up a codebase without a big rewrite
Updating a codebase's conventions without a big bang rewrite: every time you touch a file, you apply the latest rules the team agreed on.
ALL-CAPS Driven Development: shouting at AI does not work
Shouting in capital letters at an AI to enforce an architecture rule does not work: a deterministic tool can check it for you instead.
Zero hand-written code: my harness engineering experiment
I set myself the challenge of writing a program without typing a single line myself, pushing the AI harness to its limit, inspired by an OpenAI experiment.
Why I ask for an ADR before every architecture decision
An ADR fits on one page: context, decision, consequences. Michael Nygard's 2011 idea hasn't aged, and it doubles as a free guide for AI reading the repo.
Opinionated frameworks are an AI harness
AdonisJS is famously opinionated. A talk with Jonathan Serra (AI2H) on why that rigidity gives an AI an extra harness, and an open question.
Multi-tenancy: the four levels of data isolation
A SaaS handling sensitive data has to keep each customer’s data apart. Four levels, from a tenant_id column to dedicated infra, and the one I usually pick.
What is a "Model"? Two things that have nothing in common
"Model" means both an ORM Model and the DDD domain model. Confusing them makes you think you modelled your business when you only described your tables.
Functional Core, Imperative Shell: the end of mocks everywhere
Gary Bernhardt's 2012 talk Boundaries is still some of the best testing advice around: separate decisions from actions, and pass only values between them.
Sound architecture, poor features: you'll survive
Sound architecture with poor features, you survive. Shaky architecture with correct features, everything is a fight. And it is the hardest part of the job.
dependency-cruiser: a computational sensor for your AI agents
dependency-cruiser maps imports and fails CI when a boundary is violated. A sensor for AI agents that only works if the architecture is clear enough to describe.
Vertical Slice Architecture: organise code by request
When adding one field touches six files in four folders, the feature lives nowhere. Jimmy Bogard's Vertical Slice Architecture flips the way code is organised.
How many of your architecture rules break the build?
With AI, a standardised architecture becomes an asset: every rule a machine can verify is a constraint. The others are only intentions.
"A depends on B": what exactly are we talking about?
A dependency can be seen by the compiler, by a test, or by nobody. Three questions to stay precise, with developers and with an AI.
What is a "layer" in software architecture?
Abstraction, technical role, call flow, dependencies, deployment: "layer" names five ways of slicing a program, and yours probably has all of them.
Clean Architecture is one rule: the Dependency Rule
What Robert C. Martin extracted in 2012 from Hexagonal, Onion and friends: a single rule you can verify in the code, the Dependency Rule.
Onion Architecture: business code at the centre
What Jeffrey Palermo proposed in 2008 with Onion Architecture: a single dependency rule so that business code stops paying for every technology change.
Parnas and Cockburn: how their two visions fit together
Cockburn's Ports & Adapters is one tactical application of Parnas's strategy: each Port/Adapter pair is a module that hides a technology choice.
Hexagonal Architecture: Cockburn's Ports & Adapters pattern
Alistair Cockburn, 2005: think of a program as a business inside and an outside plugged in through ports and adapters, rather than as layers.
Parnas, 1972: what criterion for splitting code into modules?
In 1972, David Parnas proposed decomposing a program not by flowchart steps but so that each module hides something difficult or likely to change.
Scaling a vibe-coded MVP: when heavy operations blow up
A heavy operation the AI runs in memory holds up in a prototype, then blows up as users pile in. Without queues or observability, good luck finding why.
The best AI harness is a codebase with a rigorous architecture
DDD, TDD, hexagonal or in-house conventions: it does not matter. A rigorous codebase is the best harness to get an AI to follow your way of working.
Good code looks simple, bad code looks clever
Writing clever code that looks simple is one of the hardest things in development: behind it lie a clean split, the right abstractions and invisible choices.
Writing code is easy now. Building a system is not.
With AI, writing code has become as easy as learning to write as a child. Building a complex, coherent system that lasts is still as hard as a masterpiece.
Five types of coupling, from most acceptable to worst
External, common, control, stamp, content: five types of coupling ranked from the most acceptable to the worst, and how to keep each one in check in a codebase.
The worst thing in a codebase is coupling
Slightly rotten modules with clear interfaces will be fine. Optimised modules coupled in every direction quickly become an unmaintainable hell.
DDD + Clean Architecture: my take after 3 intense months
Three months of DDD and Clean Architecture applied to the letter on a production codebase: the pros, the cons, and why I would struggle to go without.