Architecture decisions · AI-Native Product Building

Principle

Architecture is the set of bets that are expensive to reverse — data model, auth model, deployment shape, integration boundaries. AI makes implementing any of these fast; it does not make choosing wisely automatic.

Good architecture for AI-native teams is legible: you can draw it on a whiteboard, name the modules, and say what is forbidden to import across boundaries. If only the model understands the structure, you do not have architecture — you have luck.

Before you draw boxes, name the product category: bolted-on (AI is a feature), enhanced (AI improves a traditional loop), or native (remove the model and the product breaks). That label sets which layers you must own — orchestration, context, data, evaluation, agents. See AI-native, not bolted on for the compressed decision frame.

The decision

DEC_012

  Constraints (users, compliance, team)
│
▼
ADR: choice + rejected options + why
│
▼
AI implements within boundaries
│
▼
Review: imports, data flow, failure modes

Decisions are human-owned; implementation is shared with AI.

What to decide early

Decision	Reversibility	Human owns
Monolith vs services	Low later	Yes
Database + auth provider	Low	Yes
Multi-tenant model	Very low	Yes
Event vs request-driven	Medium	Yes
Caching strategy	Medium	Yes
Folder layout	High	You + team convention

Defer microservices until pain is measured, not imagined.

ADR habit (Architecture Decision Record)

One page per bet:

Context — what forces the choice?
Decision — what we will do.
Rejected options — what we will not do and why.
Consequences — what gets easier/harder.

Store in docs/adr/ or architecture/. Link from PRs that implement the decision. Agents read ADRs before proposing structural changes.

Workflow

Sketch the system — boxes: client, API, data, jobs, third parties. Arrows labeled with data types.
Name boundaries — what may not call what directly.
Write ADR before the agent scaffolds five patterns you did not want.
Implement vertical slice — one path through the architecture in production.
Stress one failure — what happens when DB, email, or payment provider is down?
Revise ADR when reality disagrees — version in git, do not silent-drift.

AI-specific risks

Accidental microservices — new folders that become distributed mud.
Duplicate sources of truth — cache + DB + local state with no story.
Auth sprinkled — checks in random components instead of one layer.
Over-abstraction — interfaces for one implementation.

Review imports and data flow in every structural PR.

Tooling

Mermaid or Excalidraw for diagrams. ADR templates in repo. Linters for module boundaries if you outgrow discipline.

Common mistakes

Choosing stack because the model suggested it yesterday.
No written rejection — team re-litigates the same debate monthly.
Architecture for scale you do not have — operability debt on day one.
Letting agents add databases without migration story.

Artifacts

templates/adr.md — one decision per file.
System sketch — one diagram linked from README or docs/architecture.md.