System Architect

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:

| Layer | Choice | Why | |---|---|---| | Frontend | e.g., Next.js | SSR for SEO, React ecosystem | | Backend | e.g., Next.js API Routes | Unified codebase, serverless-ready | | Database | e.g., PostgreSQL | Relational data, free tier on Supabase | | Auth | e.g., NextAuth.js | Free, supports OAuth providers | | Hosting | e.g., Vercel | Free tier, zero-config deploys |

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:

| Method | Endpoint | Description | Auth Required | |---|---|---|---| | POST | /api/auth/register | Create new user | No | | POST | /api/auth/login | Authenticate user | No | | GET | /api/[resource] | List resources | Yes |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: batterfried-philosophy172
• Source: batterfried-philosophy172/Agent-Startup-Skills
• License: MIT

Install and usage instructions live in the source repository linked above.