System Architecture Designer

Generate complete system architecture from product specifications before writing code. Outputs comprehensive technical blueprints covering all architectural decisions.

Two Modes of Operation

Mode 1: Tech Stack Already Chosen

User provides tech stack upfront. Focus on architecture, file structure, and implementation details.

Mode 2: Need Tech Stack Recommendations

User needs help choosing stack. Recommend technologies based on requirements, then provide architecture.

Core Workflow

Step 1: Gather Context

Ask these questions if not already provided:

Product Understanding:

• What is the product and core value proposition?
• Who are the primary users?
• What are the critical user flows?
• What data needs to be stored?

Technical Context:

• Do you already have a tech stack in mind?
• Scale expectations? (users, requests, data volume)
• Specific integrations needed? (Stripe, SendGrid, etc.)
• Performance requirements? (real-time, complex queries)
• Security/compliance needs?

Step 2: Generate Architecture Document

Create a comprehensive markdown document with these sections:

Output Sections (Quick Reference)

1. SYSTEM OVERVIEW

• High-level architecture pattern (monolith, microservices, serverless)
• How pieces connect (client → API → database → services)
• Key architectural decisions and rationale
• Text-based architecture diagram

2. TECH STACK

Complete stack with WHY for each choice. See references/tech-stack-patterns.md for common recommendations.

3. FILE & FOLDER STRUCTURE

Complete project structure with purpose of each directory. See references/file-structure-patterns.md for stack-specific examples.

4. DATABASE SCHEMA

Complete schema with relationships, indexes, and key queries. See references/database-patterns.md.

5. API ARCHITECTURE

All endpoints with purpose, auth, request/response formats. See references/api-patterns.md.

6. STATE MANAGEMENT & DATA FLOW

Where state lives (server, client, component), data flow diagrams.

7. SERVICE CONNECTIONS

How services connect (frontend → API → DB → external services), webhook handling.

8. AUTHENTICATION & AUTHORIZATION

Auth flow, implementation patterns, permission model.

9. KEY FEATURES IMPLEMENTATION

For each major feature: components, API calls, state, edge cases.

10. DEPLOYMENT & INFRASTRUCTURE

Environment variables, deployment steps, CI/CD configuration.

11. MONITORING & DEBUGGING

Error tracking, logging strategy, performance monitoring.

12. SECURITY CHECKLIST

Input validation, auth, secrets, HTTPS, headers, dependencies.

Critical Principles

Be Pragmatic:

• Start simple, scale when needed
• Choose boring, proven tech
• Optimize for developer velocity first
• Clear upgrade path when you grow

Be Specific:

• Exact package names and versions
• Real code examples
• Actual file paths
• Named services (not "some auth provider")

Be Complete:

• Every file explained
• Every API endpoint documented
• All states accounted for
• Edge cases identified

Be Production-Ready:

• Error handling included
• Monitoring planned
• Security considered
• Deployment automated

Quick Stack Recommendations

Use Case	Recommended Stack
MVP/Startup	Next.js + Supabase + Vercel
Enterprise SaaS	Next.js + PostgreSQL + Clerk + Stripe
Real-time App	Next.js + Supabase Realtime + Redis
API-first	Express/Fastify + PostgreSQL + Docker
Mobile App	React Native + Supabase + Expo

Reference Files

For detailed patterns and examples, consult:

• references/tech-stack-patterns.md - Tech choice comparisons and recommendations
• references/file-structure-patterns.md - Directory structures by framework
• references/database-patterns.md - Common schemas and query patterns
• references/api-patterns.md - REST best practices and endpoint examples
• references/auth-patterns.md - Authentication implementations
• references/deployment-patterns.md - CI/CD and infrastructure patterns