Software architecture in the AI era: what has to stay explicit despite code generation

When writing code gets cheaper, the question “how do we implement this?” loses weight – and “how do we carve this up?” gains it. Architecture was never unimportant, but for a long time the cost of implementation protected it: choosing the wrong structure hurt, so you noticed. That protection is gone.

1. Where the value moved

A model produces code that fits what it sees. It does not produce the decision about what belongs together, where a boundary runs and which assumption will be expensive in two years. Yet exactly those decisions determine whether a system stays maintainable.

There is a second, practical effect: everything that exists explicitly is also the context an agent works from. Architecture work therefore pays twice – on maintainability and on the quality of what gets generated.

2. Boundaries are the first decision

The architecture decision with the widest consequences is rarely the choice of technology but the cut: which parts of a system may know about each other? Without guidance a model takes the shortest path – accessing directly whatever data structure it happens to see.

The effective countermeasures are unspectacular:

• Module boundaries visible in the directory tree, not only in the concept.
• Dependency rules that are checked – a test that fails on forbidden imports is worth more than any diagram.
• A named direction. Domain logic does not know about infrastructure; the reverse is allowed.

3. Contracts instead of agreements

Wherever two parts are built independently – frontend and backend, service and service, system and third-party system – there should be a machine-readable contract: OpenAPI, JSON Schema, an event schema. A contract has three properties a verbal agreement does not: it is checkable, it is versionable, and tools can read it.

The deep dive OpenAPI as a contract covers the most important individual case in detail, including contract tests and how to handle breaking changes.

4. Keeping the data model explicit

The data model is the longest-lived part of a system. Applications get rewritten, interfaces replaced, frameworks swapped – the data stays. Yet in many projects it arises as a by-product: first the code, then the table.

Explicit here means concretely:

• entities, fields and relations named and documented,
• mandatory fields, value ranges and validation rules as part of the model, not scattered across controllers,
• tenant and organisation context considered from the start – retrofitting it is extremely expensive,
• history where traceability is required.

An explicit model is checkable, comparable and can be held against a requirement. A convention spread across twenty classes is none of those – neither for people nor for tools.

5. Permissions belong in the model

The most common weakness in generated code is not authentication but fine-grained authorisation: may this person see or change this record? If that rule is not modelled, it gets reinvented per endpoint – and forgotten somewhere.

What holds up is a structure in which roles, permissions and visibility rules exist as a model of their own and are enforced in one central place. It is also the part that reuses best – see platform instead of boilerplate.

6. Documenting decisions

Short, dated architecture notes are the cheapest tool with the best effect. Four lines are enough: context, decision, alternatives, consequences. What matters is the place – in the repository, next to the code, not in a system the next change of tooling clears away.

# ADR-014: Tenant isolation via row-level scoping

Context     Multi-tenant deployment, shared database, ~40 tenants.
Decision    Every tenant-owned table carries tenant_id; access goes
            through a scoped repository that always applies the filter.
Rejected    Schema-per-tenant (operational cost), database-per-tenant
            (migration cost at this scale).
Consequence No direct repository access outside the scoped layer.
            Enforced by an architecture test.

Such notes answer the question code never answers: why. They are valuable for new team members, useful in audits, and the most effective context you can give an agent.

7. Architectural erosion at speed

Erosion does not come from one big wrong decision but from many small deviations that each look defensible. At a higher rate of change, that process accelerates accordingly.

Three countermeasures that work day to day:

1. Check the rules automatically. Dependency tests, lint rules for layering violations, schema checks. Whatever the pipeline lets through will happen.
2. Keep change sets small. Large diffs hide structural breaks reliably.
3. Document deliberate exceptions instead of allowing them silently – a recorded exception is a decision, an unrecorded one is a precedent.

8. Architecture as context for agents

Everything named so far has a practical side effect: it is exactly the material a coding agent produces good results from. Contracts tell it what is allowed. The data model tells it what the domain looks like. Architecture notes tell it why certain routes are ruled out. Architecture tests tell it – through the pipeline – when it gets it wrong anyway.

That is the real reason architecture work gains value in the AI era: it is no longer just documentation for people but control information for the tool chain.

Common mistakes

• Trying to settle the architecture after generation – by then the code has created facts.
• Diagrams without enforcement. A picture no test checks describes a wish.
• The data model as a by-product of the implementation.
• Permissions per endpoint instead of as a model.
• Deferring multi-tenancy – retrofitted, it is a rebuild project.
• Decisions in chat rather than in the repository.

Checklist: keeping architecture explicit

Conclusion

Code generation does not devalue architecture – it reveals how much architecture a project actually had. Where boundaries, contracts, data model and permissions are explicit, an agent becomes a very fast, very patient implementer. Where they are missing, it quickly produces a lot of code that is hard to change later.

The work therefore moves to where it was always most valuable: to the front, to structure. That is not a new insight – but it has rarely had such immediate practical consequences.