Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture

Pattern

A reusable solution you can apply to your work.

“Architecture is the decisions you wish you could get right early.” — Ralph Johnson

Context

Once a team (or an agent) knows what to build, the next question is how to organize the whole thing. Architecture operates at the architectural scale: it’s the large-scale shape of a system, the choice of major components, the way data flows between them, and the reasoning that led to those choices. It sits above the code but below the product strategy, bridging intent and implementation.

Architecture isn’t a diagram. It’s a set of constraints, some chosen, some inherited, that guide every decision downstream. A well-chosen architecture makes the common cases easy and the hard cases possible. A poorly chosen one makes everything hard.

Problem

How do you give a system a structure that survives contact with reality (changing requirements, growing teams, evolving technology) without over-engineering it from the start?

Forces

  • You need to make structural decisions before you have full information.
  • Changing architecture later is expensive, but guessing wrong early is also expensive.
  • Different parts of a system may need different styles (a batch pipeline and a real-time API have different concerns).
  • The architecture must be understandable not just to its creators but to everyone who will work on it, including AI agents.

Solution

Treat architecture as the set of decisions that are costly to reverse. Focus your early effort there and leave everything else flexible. Identify the key boundaries: where does the system end, where do its major parts divide, what crosses those lines? Choose patterns for communication: does data flow through a shared database, through APIs, through events? Document the why behind each choice, not just the what.

Good architecture isn’t about picking the trendiest style. It’s about matching the structure to the forces at hand: the team’s size, the expected rate of change, the deployment constraints, and the nature of the domain. A small team building a single product may thrive with a monolith. A platform serving many consumers may need explicit interfaces and strict contracts.

In agentic workflows, architecture also determines how effectively an AI agent can work with the system. Clear boundaries and well-defined modules give an agent a manageable scope. An architecture where every file depends on every other file forces the agent to load everything into its context window, and that’s a recipe for mistakes.

How It Plays Out

A startup building a new web application chooses a straightforward three-layer architecture: a React frontend, a REST API, and a PostgreSQL database. The layers are separated by clear interfaces. When the team later needs to add a mobile client, the API layer is already there — the mobile app just becomes another consumer.

Agentic coding workflows benefit from explicit architecture. When you tell an agent “add a caching layer to the data access module,” the agent needs to know where that module lives, what it depends on, and what depends on it. If the architecture is documented and the boundaries are clear, the agent can do this confidently. If the system is a tangle of implicit connections, even a capable agent will introduce regressions.

Tip

When working with AI agents, keep an architecture document (even a brief one) in the repository root. The agent can read it to orient itself before making changes.

Example Prompt

“Read the architecture document in docs/architecture.md. The system has three layers: React frontend, REST API, and PostgreSQL database. Add the caching feature to the data access layer without crossing into the API layer.”

Consequences

A clear architecture reduces the cognitive load on everyone who works on the system, human or agent. It makes decomposition possible by defining where the seams are. It constrains future choices, which is both its power and its cost: an architecture that’s too rigid will fight you when requirements shift, while one that’s too loose provides no guidance at all.

Architecture decisions tend to be self-reinforcing. Once you’ve chosen a layered style, new code flows into those layers. This helps when the architecture fits the problem and hurts when it doesn’t. Revisiting architecture periodically, asking “does this shape still serve us?”, is one of the most valuable things a team can do.

  • Refines: Shape — architecture is the shape at the system level.
  • Uses: Component, Boundary, Interface — the building blocks of architectural decisions.
  • Enables: Decomposition, Separation of Concerns — architecture makes principled splitting possible.
  • Contrasts with: Monolith — a monolith is one particular architectural choice, not the absence of architecture.
  • Violated by: Big Ball of Mud – the absence of architecture produces an undifferentiated tangle.
  • Related: Technical Debt – architectural debt is the most expensive kind.