2026-09-10
Software Orchestrator Series · Part 5 of 6
Architecture Before Code: Designing Systems AI Can Build Inside
Generated code only earns its keep when it fits the system it lands in. That fit is designed up front — boundaries, contracts, and conventions codified in the repository before anyone, human or AI, writes a line.
Editor's Note: This post is part of The Software Orchestrator Framework. For the foundational principles and vocabulary that make this method possible, start with Phase 1: The Foundation.
The most common failure of AI-assisted work is not that the output is wrong in isolation. It compiles, it renders, it passes a smoke test. The failure is that it does not fit: it ignores a boundary, duplicates a responsibility, reaches into a module it should not know about. Fixing that after the fact is expensive. Designing it up front is architecture — and it happens before code, whoever writes it.
What "Fit" Means
Fit is decided, not discovered. Before a change is generated, the important questions already have answers:
| Question | Answer lives in |
|---|---|
| What belongs together, and what stays separate? | Module and ownership boundaries |
| What may depend on what? | Dependency rules |
| How is state and configuration handled? | Environment and data conventions |
| How do failures behave? | Error handling and resilience contracts |
| What must never change about this system? | Binding decisions and their rationale |
When these answers exist, a capable drafter — human or AI — produces work that slots in. When they do not, every addition nudges the system toward entropy, and the drift is silent until it bites.
Boundaries First
Well-defined boundaries are the highest-leverage structure you can draw:
- Modules with one responsibility, so a change has an obvious home.
- Explicit dependency direction, so layers do not tangle.
- Narrow interfaces, so internal changes stay internal.
AI accelerates whatever shape it finds. Inside clear boundaries, it produces more of that clarity. Inside a tangle, it produces more tangle — faster than any human could. The fix is not better prompting; it is a better shape to prompt inside.
Codify the Map
Architecture that lives in someone's head is not architecture; it is memory. The durable form is a version-controlled map in the repository that records:
- the structure — modules, layers, boundaries, and how they connect;
- the conventions — naming, error handling, configuration, testing;
- the decisions — what was chosen, why, and what it replaced.
A new engineer reads that map to get oriented. An AI session reads the same map for the same reason. Neither of them owns it; the repository does, and every change to it is a reviewed change.
Cheap to State, Expensive to Rediscover
The most valuable conventions are the ones that cost one line to write and weeks to rediscover: where config belongs, how a service reports failure, when something may cross a boundary, what naming pattern keeps logs and dashboards searchable. Codify those in the map, and the assistant's drafts inherit them for free. Leave them out, and you will spend review cycles explaining them one generated change at a time.
Architecture Is a Judgment Call
None of this removes the engineer. Choosing boundaries means trading off coupling, reuse, and ownership — and defending the trade-off. Those are judgment calls, and judgment is exactly what the orchestrator keeps. A model can draft options and even analyse trade-offs; deciding which system you are willing to maintain is human work, and it stays human.
Next in the Series
Structure that is designed still needs to be trusted. The final post covers how quality becomes a property of the process: automation and gates that enforce the standards on every change, with no express lane for generated code.