Structure and Decomposition

Every system has a shape. Whether you’re building a mobile app, a data pipeline, or an agent-driven workflow, how you divide work into parts (and how those parts relate) determines how easy the system is to understand, change, and extend. This section covers the architectural level: the decisions that give a system its skeleton.

These patterns address the questions that come up once you know what to build but need to decide how to organize it. Where should the boundaries fall? Which pieces should know about each other? What should be hidden, and what exposed? Get these right and a system stays manageable as it grows. Get them wrong and every change turns into a negotiation with the whole codebase.

In agentic coding, structure matters even more. An AI agent working in a well-decomposed system can focus on one module without needing the full picture. A tangled monolith overwhelms the agent’s context window and invites cascading mistakes. Good decomposition isn’t just good engineering; it’s a precondition for effective agent collaboration.

Concepts and Vocabulary

The foundational ideas for thinking about structure at any scale.

• Architecture — The large-scale shape of a system and the reasoning behind it.
• Shape — The structural form of something as seen at a particular level.
• Abstraction — Hides irrelevant detail so you can reason at the right level.

Building Blocks

The parts a system is made of and the surfaces they expose to each other.

• Component — A bounded part of a larger system with a clear role and interface.
• Module — A unit of code or behavior grouped around a coherent responsibility.
• Interface — The surface through which something is used.
• Consumer — The code, user, system, or agent that relies on an interface.
• Contract — An explicit or implicit promise about behavior across an interface.
• Boundary — The line where one part of a system stops and another begins.

Relationships

How parts connect, depend on each other, and stay (or fail to stay) independent.

• Cohesion — How well the contents of a module belong together.
• Coupling — How much the parts of a system depend on one another.
• Dependency — Something a component relies on to function.
• Composition — Building larger behavior by combining smaller parts.
• Separation of Concerns — Keeping different reasons to change in different places.

Breaking Things Apart

From monoliths to manageable pieces: the patterns and antipatterns of decomposition.

• Monolith — A system built, deployed, or evolved as one tightly unified unit.
• Decomposition — Breaking a larger system into smaller parts.
• Task Decomposition — Breaking a larger goal into bounded units of work with clear acceptance criteria.
• Big Ball of Mud — A system that grew without structure until no one can change one part without breaking another.