Step 3: Architecture Decisions

What your agent does

For every significant technical choice — framework, database, ORM, styling, auth, hosting — the agent creates an Architecture Decision Record (ADR) documenting what was chosen, why, and what alternatives were considered.

Why this matters

Three months from now, someone (probably you) will ask: "Why did we use SQLite instead of Postgres?" or "Why Next.js and not Remix?" The answer is in the ADR. No archaeology through chat logs, no guessing.

ADRs also prevent flip-flopping. Once a decision is recorded, it stays unless someone writes a new ADR explicitly superseding it.

What the output looks like

Your agent creates docs/adr/ADR-001-*.md through ADR-00N-*.md:

# ADR-001: Frontend Framework — Next.js 15

## Status
Accepted

## Context
Need a frontend framework for the dashboard.

## Decision
Next.js 15 with App Router. Built-in API routes, Vercel deployment, 
excellent TypeScript support.

## Consequences
- Easier: Deployment is seamless. Server components reduce client JS.
- Harder: App Router has a learning curve. Locked into React.

## Alternatives Considered
- Remix: Strong data loading but smaller ecosystem.
- SvelteKit: Lighter but less team experience.

Plus docs/adr/README.md — an index of all decisions.

Minimum ADRs

Every project should have decisions recorded for:

1. Frontend framework — what renders the UI

2. Database — where data lives

3. ORM/data access — how code talks to the database

4. Styling — CSS approach

5. Authentication — how users log in

6. Hosting — where it deploys

Your role

Optionally override. The agent picks sensible defaults (Next.js, SQLite for local dev, Tailwind, etc.) but you can tell it to use something different:

> "Use Remix instead of Next.js" or "I need PostgreSQL, not SQLite"

The agent will update the ADRs and adjust the implementation plan accordingly.

Next: Planning the build →