architect

Architecture Discussion — Phase 4

Design the technical architecture for: $ARGUMENTS

Prerequisites

Read:

• output/<slug>/01-discovery.md — features to implement
• output/<slug>/02-competitive.md — tech landscape
• output/<slug>/03-validation.md — MVP scope and priorities

If they don't exist, tell the user to run earlier phases first.

Process

This phase works like Plan mode — present options with trade-offs at each decision point. Use AskUserQuestion with options and previews for structured choices.

Work through decisions sequentially. Each decision informs the next.

Decision 1: Tech Stack

Based on the MVP scope and features, present 2-3 tech stack options. For each:

• Language + framework
• Why it fits this project
• Pros and cons
• Ecosystem maturity
• Hiring pool / community size
• Example: which competitors use it

Use AskUserQuestion with previews showing a sample project structure for each option.

Decision 2: Architecture Style

Present options appropriate for the project scale:

• Monolith — single deployable, fastest to MVP
• Modular monolith — logical separation, easy to split later
• Microservices — independent services (usually overkill for MVP)
• Serverless — event-driven, pay-per-use

For each, show: pros, cons, estimated time to MVP, scaling characteristics.

Use AskUserQuestion with preview showing architecture diagram (ASCII) for each.

Decision 3: Database & Data Model

Based on chosen stack, present:

• Database options (PostgreSQL, MySQL, MongoDB, etc.) with trade-offs
• Present a draft data model as a mermaid ER diagram based on the features
• Key entities, relationships, and attributes

Show the mermaid diagram. Ask user to review and refine.

Decision 4: API Design

Present:

• API style options (REST, GraphQL, tRPC, gRPC) with trade-offs for this project
• Authentication strategy (JWT, session, OAuth, magic links)
• Draft of core endpoint groups based on features

Show endpoint structure. Ask user to adjust.

Decision 5: Frontend Approach

Present options:

• SPA (React, Vue, Svelte) — rich interactivity
• SSR (Next.js, Nuxt, SvelteKit) — SEO + performance
• Hybrid — SSR for marketing, SPA for app
• No frontend — API-only (if applicable)

Include: component library recommendations, styling approach (Tailwind, CSS-in-JS, etc.)

Decision 6: Infrastructure & Deployment

Present options with estimated monthly costs:

• Cloud provider (AWS, GCP, Vercel, Railway, Fly.io, etc.)
• Deployment strategy (container, serverless, PaaS)
• CI/CD approach
• Monitoring and logging
• Cost at 100 users, 1K users, 10K users

Record Decisions

After all 6 decisions, write consolidated results to output/<slug>/04-architecture-decisions.md:

# Architecture Decisions

## Summary
| Decision | Choice | Key Reason |
|----------|--------|-----------|
| Tech Stack | ... | ... |
| Architecture | ... | ... |
| Database | ... | ... |
| API Style | ... | ... |
| Frontend | ... | ... |
| Infrastructure | ... | ... |

## Detail
[Full reasoning and trade-offs for each decision]

## Architecture Diagram
[Mermaid diagram showing the full system architecture]

## Data Model
[Mermaid ER diagram]

Guidelines

• Always present at least 2 options — never prescribe without discussion
• Include cost implications where relevant
• Reference what competitors use (from Phase 2) as context, not as prescription
• Be honest about trade-offs — every choice has downsides
• If user asks about an option you didn't present, research it and give an honest assessment
• Tailor complexity to the MVP scope — don't over-engineer