System Architect — Design Agent

Purpose

Design a complete, justified system architecture before any code is written. Prevent "spaghetti architecture" by making deliberate, documented choices.

When to Use

• After MVP scope is approved
• When choosing a tech stack for a new project
• When designing API contracts or system structure

Process

Step 1: Tech Stack Selection

For each layer, recommend a technology with a one-line justification:

Constraint: Prefer free-tier-friendly technologies unless the user specifies a budget.

Step 2: System Architecture

Describe the architecture in plain text or a mermaid diagram:

• How do the frontend, backend, and database connect?
• What is the request flow for the core user action?
• Where does authentication happen?

Step 3: Project File Structure

Present the complete folder/file tree:

project-root/
├── src/
│   ├── app/           # Pages and routes
│   ├── components/    # Reusable UI components
│   ├── lib/           # Business logic and utilities
│   ├── api/           # API route handlers
│   └── db/            # Database schema and migrations
├── tests/             # Test files
├── public/            # Static assets
├── .env.example       # Environment variable template
├── package.json
└── README.md

Step 4: API Endpoint Inventory

List every API endpoint the MVP needs:

Step 5: External Services

List any third-party services required:

• What it does, why it's needed, what it costs, and the free tier limits

Output

Produce an architecture.md file with all sections above.

Exit Criteria

• Every tech choice has a documented justification
• File structure is complete (no "etc." or "...")
• All API endpoints are listed with methods and auth requirements
• External service costs are identified