Documenting Architecture for AI: Describe Boundaries and Decisions

AI Summary: Documenting software architecture for AI coding agents requires moving beyond static visual diagrams to establish machine-readable system boundaries, data ownership contracts, and Architecture Decision Records (ADRs). When agents understand why architectural trade-offs were chosen, they cease proposing rejected designs and respect established network and state boundaries.

#The Architectural Amnesia of AI Coding Agents

When an LLM coding agent (such as Cursor Composer, Claude Code, or Devin) is tasked with building a feature or debugging an error, it suffers from Architectural Amnesia:

• It evaluates the codebase purely as a collection of syntax files.
• It lacks the historical memory of past engineering debates and rejected proposals.
• When facing a state management challenge, it will eagerly recommend introducing Redux, an external Redis broker, or a microservice split—completely unaware that your team deliberately chose a modular monolithic architecture with SQLite storage.

To prevent agents from continually re-introducing rejected architectural patterns, repositories must document Boundaries, Containers, and ADRs.

#The C4 Model Tailored for LLM Ingestion

The C4 Model (Context, Containers, Components, Code) provides an exceptional framework for agent orientation when represented in Markdown:

[Level 1: System Context] ──► What does this service own vs external third parties?
            │
            ▼
[Level 2: Containers]     ──► What runtimes exist? (Next.js Edge Worker, Postgres, Redis)
            │
            ▼
[Level 3: Components]     ──► Key modules (Content Loader, Scan Orchestrator, Tokenizer)
            │
            ▼
[Level 4: Code]           ──► Abstract Syntax Trees & Interfaces (Covered by repo maps)

#Production Architecture Documentation (docs/ARCHITECTURE.md)

# Acme Platform Architecture

## Level 1: System Context & External Boundaries
- **Inbound Clients**: Web browsers, IDE agents (Cursor/Claude Code via /llms.txt).
- **Outbound Dependencies**: Cloudflare KV (read-through cache), PostHog (analytics).
- **Hard Security Boundary**: All outbound HTTP fetches must pass through `src/lib/safe-fetch.ts` to block internal IP ranges (127.0.0.1, 169.254.169.254).

## Level 2: Runtime Containers & Data Flow
- **Next.js App Router**: Runs on Cloudflare Workers edge runtime.
  - Server Components (RSC): Handle data fetching, MDX compilation, and SEO tags.
  - Client Components: Restricted to interactive UI state (modals, copy buttons).
- **Storage Tier**: In-memory LRU cache with Cloudflare R2 persistence for generated bundles.

#Architecture Decision Records (ADRs) as Negative Constraints

Architecture Decision Records (ADRs) are short Markdown documents recording significant technical decisions, their context, and consequences. For AI agents, ADRs function as Immutable Negative Constraints.

#Production ADR Template (docs/adr/ADR-0004-vanilla-css-vs-tailwind.md)

# ADR-0004: Pure Vanilla CSS Over TailwindCSS

## Status: Accepted (2026-08-15)

## Context
Our platform delivers technical documentation and generator tools across edge runtimes. 
We evaluated TailwindCSS v4 versus Vanilla CSS design tokens.

## Decision
We mandate pure Vanilla CSS with CSS custom properties (`var(--teal)`, `var(--panel)`). 
TailwindCSS utility classes are strictly prohibited.

## Consequences for Coding Agents
- NEVER generate Tailwind utility classes (`flex items-center text-sm font-bold`).
- ALWAYS write semantic classes in `src/app/globals.css` using predefined CSS variables.
- Reject pull requests that import `@tailwindcss/postcss` or Tailwind plugins.

When an agent indexes this ADR, it immediately refrains from writing Tailwind utility soup, adhering to your team's design system without manual correction.

#Architecture Documentation Checklist for Agents

#Related guidance

To understand how to navigate multi-tiered repositories, review Codebase Context Strategies, study repository rules in AGENTS.md Best Practices, and learn how to format documentation in Markdown for RAG.

#References

• The C4 Model for Visualizing Software Architecture: Simon Brown's hierarchical architecture abstraction methodology.
• Michael Nygard: Architecture Decision Records (ADR): The original specification for capturing architectural choices in version control.

Need to optimize your entire site for AI search visibility? Run a comprehensive audit with Geolify.ai.