Software Architecture Doc Template for AI Coding

TL;DR: This architecture template prevents AI tools from mixing patterns, using wrong integrations, and creating architectural drift.

Table of Contents

1. Why Architecture Docs?
2. The Template
3. How to Use
4. Common Mistakes
5. Related Templates

---

Why Architecture Docs for AI?

Without an architecture doc, AI tools:

• Mix REST and GraphQL in the same project
• Use wrong database syntax (MongoDB in Postgres project)
• Create components that don't match your design system
• Integrate with services you're not using

---

The Template

## [Project Name] — Architecture Document

**Version:** 1.0
**Last Updated:** [Date]
**Author:** [Name]

---

## 1. System Overview

### High-Level Diagram

```mermaid
graph TB
    subgraph Client
        A[Web App]
    end

    subgraph Backend
        B[Next.js API]
        C[Background Jobs]
    end

    subgraph Data
        D[(PostgreSQL)]
        E[File Storage]
    end

    subgraph External
        F[Auth Provider]
        G[Email Service]
        H[LLM API]
    end

    A --> B
    B --> D
    B --> E
    B --> F
    B --> G
    C --> H
    C --> D
```

System Description

[1-2 paragraphs describing what the system does and how the major components interact]

---

2. Component Inventory

Frontend

Component	Technology	Purpose
Web App	Next.js 14 (App Router)	Main user interface
UI Library	shadcn/ui	Component system
Styling	Tailwind CSS	Utility-first CSS
State	React Context / Zustand	Client state

Backend

Component	Technology	Purpose
API	Next.js API Routes	REST endpoints
Auth	Supabase Auth	Authentication
Database	PostgreSQL (Supabase)	Data persistence
Jobs	Inngest	Background processing

External Services

Service	Provider	Purpose
LLM	OpenAI / Anthropic	AI features
Email	Resend	Transactional email
Storage	Supabase Storage	File uploads

---

3. Data Flow

[Flow Name]: [Description]

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database

    User->>Frontend: [Action]
    Frontend->>API: [Request]
    API->>Database: [Query]
    Database-->>API: [Data]
    API-->>Frontend: [Response]
    Frontend-->>User: [UI Update]

1. User [does action]
2. Frontend [sends request]
3. API [processes/validates]
4. Database [stores/retrieves]
5. Response [returned to user]

---

4. API Patterns

REST Conventions

GET    /api/[resource]         List
POST   /api/[resource]         Create
GET    /api/[resource]/[id]    Get by ID
PATCH  /api/[resource]/[id]    Update
DELETE /api/[resource]/[id]    Delete

Request/Response Format

All responses follow this shape:

// Success
{
  data: T,
  meta?: PaginationMeta
}

// Error
{
  error: string,
  message: string,
  details?: object
}

Authentication

• Bearer token in Authorization header
• Token obtained from Supabase Auth
• Include Authorization: Bearer <token> on all authenticated requests

---

5. Directory Structure

src/
├── app/                    # Next.js App Router
│   ├── (app)/              # Authenticated routes
│   ├── (marketing)/        # Public routes
│   ├── api/                # API routes
│   └── layout.tsx          # Root layout
├── components/
│   ├── ui/                 # shadcn/ui components
│   └── [feature]/          # Feature components
├── lib/
│   ├── supabase/           # Supabase clients
│   └── utils.ts            # Utilities
└── types/                  # TypeScript types

---

6. Patterns & Conventions

Naming

• Components: PascalCase (ProjectCard.tsx)
• Files: kebab-case (project-card.tsx) or PascalCase
• Functions: camelCase (getProjects())
• Types: PascalCase (ProjectType)
• Constants: UPPER_SNAKE_CASE (MAX_PROJECTS)

Data Fetching

• Server Components: Direct Supabase calls
• Client Components: API routes via fetch
• Background: Inngest functions

Error Handling

• API: Return standard error shape
• Client: Show toast + log to console
• Critical: Report to error service

---

7. Security

Authentication

• Supabase Auth (JWT)
• Protected routes via middleware
• Session stored in cookies

Authorization

• Row-Level Security (RLS) in Supabase
• API route checks for ownership
• Admin routes check role

Data Protection

• HTTPS everywhere
• Passwords never stored (auth provider)
• Sensitive data encrypted at rest

---

8. Deployment

Environments

Environment	URL	Purpose
Local	localhost:3000	Development
Preview	vercel preview URL	PR review
Production	[domain]	Live

Infrastructure

• Hosting: Vercel
• Database: Supabase
• CDN: Vercel Edge
• DNS: [Provider]

---

9. Appendix

NOT Using (Explicit Exclusions)

AI tools should NOT use these:

• ❌ GraphQL (we use REST)
• ❌ MongoDB (we use PostgreSQL)
• ❌ Redux (we use Context/Zustand)
• ❌ Styled Components (we use Tailwind)
• ❌ Express.js (we use Next.js API routes)

---

## How to Use 

### 1. Copy and Customize

Replace all `[placeholder]` values with your project specifics.

### 2. Add to Repo

your-project/ ├── docs/ │ └── architecture.md # ← This file ├── src/ └── ...

### 3. Reference in AI Prompts

**Cursor:**

Using @docs/architecture.md, implement the data fetching pattern.

**Cline:**

Check architecture.md before implementing. Use only the technologies listed.

---

## Common Mistakes 

| Mistake | Problem | Fix |
|---------|---------|-----|
| Missing "NOT Using" | AI uses random tech | Explicitly exclude alternatives |
| No directory structure | Files created randomly | Document expected structure |
| Vague patterns | Inconsistent implementations | Specific conventions |
| Outdated diagrams | Drift from reality | Update when architecture changes |

---

## Related Templates 

- [Full Architecture Template Download](/templates/architecture-doc-template)
- [API Spec Template](/templates/api-spec-template-openapi-ai)
- [Database Schema Template](/templates/database-schema-spec-template)
- [SDD Template Pack](/templates/spec-driven-development-template)

---

> **Architecture that AI respects.** [Generate your docs →](/)

---

*Last updated: January 2026*