Shed Logic: Build Boundaries Your Team Can Explain
Photo: John Darch, CC BY-SA 2.0, via Wikimedia Commons
A garden shed is a small building with a serious job. It keeps the mower dry, the paint out of the kitchen and the awkward stuff out of the house. It has a door, a lock, a base and a rule about what belongs inside. Good software boundaries are like that. Not grand architecture. Not a cathedral plan. A shed you can point at and explain.
Most tangled builds do not start tangled. They start with a sensible shortcut. A helper here, a shared model there, a direct database call because the service was right there. Two years later the build graph looks like a hedge that has not been cut since the last Jubilee. New starters are handed a whiteboard marker and a diagram with forty arrows. That is not architecture. It is a maze with a CI pipeline.
Start with the allotment, not the cathedral
The shed metaphor is useful because it keeps boundaries modest. A shed has one main purpose. It has an edge you can see. It has an owner who knows where the key is. It does not try to be the house, the garage and the corner shop at once.
A service or module should feel the same. It should have a job, a public door and a private interior. Other parts of the system should knock at the door rather than climb through the window. The owner should be clear. The rules about what can go inside should be written down, not implied by whoever happened to write the first commit.
Audit the graph before you draw
Before you move anything, look at the build graph as it actually is. Not the diagram in the onboarding deck. The real one. Use a dependency tool, import analysis or whatever your language ecosystem gives you. Then note four things.
First, cycles. If package A imports B, B imports C and C imports A, you do not have three modules. You have one module wearing three coats.
Second, shared code that changes for unrelated reasons. If a utilities package contains date formatting, permission checks and a random retry helper, it is not cohesive. It is a drawer full of batteries and old chargers.
Third, deployment units. Which parts are built together, tested together and released together? That is often a better clue to a boundary than the folder structure.
Fourth, ownership. Who gets the pull request when this area breaks? If nobody knows, or if everyone is expected to know, the boundary is probably fictional.
Choose boundaries that follow change
A useful boundary usually follows a change that happens together. Billing rules change together. Address validation changes together. Search ranking changes together. If two pieces of code almost always change in the same pull request, forcing them apart can create ceremony without clarity. If two pieces change for completely different reasons but share a database table, that is a boundary worth investigating.
The shed test is simple. Can you describe the boundary in one sentence without using the word and more than once? The address service validates and stores UK addresses for other systems. That is a shed. The platform module handles users, payments, emails, permissions and reporting is a barn with the doors nailed shut.
Also decide what must stay outside. A shed is defined as much by what it excludes as by what it stores. Should the address service know about billing? Should the web app talk directly to the database? Should the reporting job call internal functions in the checkout service? Write those exclusions down. Boundaries are easier to enforce when the no list is explicit.
One door, one owner
Every boundary needs a public door. In practice that means a small API, a package entry point, a message contract or a documented interface. It does not mean every function in the folder is fair game. If other teams can import the internals, the door is decorative.
Ownership matters too. A boundary with no owner becomes a corridor. Everyone passes through, nobody repairs the lock. Put a team or a named maintainer against each boundary in your code owners file. Give them the authority to say no to new dependencies that blur the edge.
Then enforce the boundary in the build. Dependency linting, package rules, import restrictions and contract tests are all ways of making the shed wall real. A rule that lives only in a wiki is a suggestion. A rule that fails CI is a boundary.
Write the label, not the maze
Once you have chosen a boundary, write a one-page note for it. Keep it short enough that someone will read it before their first coffee. Include the purpose, the owner, the public interface, the data it owns, what it must not import and how to run its tests.
For bigger decisions, use an architecture decision record. Record why the boundary exists, what alternatives were considered and what would cause you to revisit it. That last part is important. Boundaries are not eternal. They are maintenance decisions with a date on them.
Draw a simple map. A few boxes with arrows is fine. If the diagram needs a legend, three colours and a magnifying glass, it is probably hiding a problem rather than explaining one.
The new starter test
Ask a new starter to explain where a new feature would go. Not with a whiteboard. In conversation. If they can say that the web app calls the address service, the address service owns validation and storage, and billing reads a snapshot, then your boundaries are doing their job. If they pause, point at three boxes and say it depends, you have found your next piece of documentation work.
The aim is not a perfect architecture. The aim is a set of small, purposeful spaces that people can explain, own and change without fear. Shed logic, not cathedral ambition. A good boundary is one your team can describe on the walk back from the kettle.