2.2.3 - Understanding the Shape of the System Before You Change It

System shape

Is the system shape clear?

The call

Map the boundaries before building across them. Otherwise AI helps you connect parts that should have stayed separate.

Why it matters

Understanding the shape of the system means making boundaries visible before complexity spreads. AI can generate implementation options quickly, but human judgement decides which path preserves reliability and clarity for users. The difference is between a system that scales with confidence and one that accumulates hidden risk.

Explainer

System shape is not an abstract architecture diagram. It is the practical boundary between parts, the dependencies they carry and the handoffs that matter. Until you can name one boundary, one dependency and one handoff between parts, design decisions stay fuzzy. AI can help sketch architecture, but it cannot decide which boundary reduces risk in your system.

Make the system shape concrete

Compare the broad version with a version you can actually test.

• Too vague: The system has a few services that connect together.
• Concrete enough to test: The frontend handles the search interface and user context. The Worker orchestrates auth checks, database reads and AI search calls. The database stores preferences and history. Auth is handled externally. Each part has one job and one clear handoff to the next.

The second version lets two people draw the same core boundaries from it.

Check the system shape

• Pass: You can say which part owns what, what each part depends on and where the important handoff happens.
• Fail: If architecture still means a rough stack or a list of services, the system shape is not clear enough yet.

Do not move into system design or implementation work until this passes.

What you'll walk away with

This post is about the framing decision: the words that pin down what this idea actually means for your build, before any code. You'll come out with your own knowledge-base/build/system-shape.md written and sharpened: the system shape pinned down as a decision, three worked examples to map against your own surface and an AI prompt that pressure-tests it until two people would make the same call.

The code that brings these decisions to life lives in the build-in-public repos (subCancel, ghostMarketingFlow and flowRun), which are works in progress growing alongside the writing. We work through the code together each week in the free weekly workshops; that is where these ideas get put into practice with hands on the keyboard.

If you sign up, this idea continues with how it all fits together, a worked example, how to use it with AI, how to evaluate it on a real change, the risks worth naming and how to mitigate them, the key takeaways and a copy-paste AI prompt you can drop straight into your next chat. Examples are shown on the Cloudflare Workers stack with AI-assisted coding tools; the ideas apply equally on any other platform.