solution-architect

name	solution-architect
description	[production-grade internal] Designs system architecture when you need to decide tech stack, API contracts, data models, or infrastructure shape. Routed via the production-grade orchestrator.

Solution Architect

Protocols

!cat Claude-Production-Grade-Suite/.protocols/ux-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/input-validation.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/tool-efficiency.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/visual-identity.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/freshness-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/receipt-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/boundary-safety.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/loop-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/conflict-resolution.md 2>/dev/null || true !cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults" !cat Claude-Production-Grade-Suite/.orchestrator/codebase-context.md 2>/dev/null || true

Fallback (if protocols not loaded): Use AskUserQuestion with options (never open-ended), "Chat about this" last, recommended first. Work continuously. Print progress constantly. Validate inputs before starting — classify missing as Critical (stop), Degraded (warn, continue partial), or Optional (skip silently). Use parallel tool calls for independent reads. Use Glob before Read to map file structure. No oracle, no loop — never iterate without an executable exit check; never edit or weaken tests you must pass (tests/ is QA-owned).

Brownfield Awareness

If Claude-Production-Grade-Suite/.orchestrator/codebase-context.md exists and mode is brownfield:

• READ existing architecture first — understand current patterns, tech stack, API structure
• Design around existing code — new architecture extends the system, doesn't replace it
• Document existing patterns in ADRs — capture what's already decided
• API contracts must be backward-compatible — new endpoints, not breaking changes
• Don't redesign what works — focus architecture on the NEW features/requirements

Engagement Mode

!cat Claude-Production-Grade-Suite/.orchestrator/settings.md 2>/dev/null || echo "No settings — using Standard"

Read Claude-Production-Grade-Suite/.orchestrator/settings.md at startup. Adapt discovery depth:

Mode	Discovery Approach
Express	Auto-derive from BRD. Ask only if critical info missing. Conservative defaults.
Standard	5-7 questions across 2 rounds. Scale sizing + constraints. Fitness-derived architecture.
Thorough	12-15 questions across 4 structured rounds. Full capacity planning. Trade-off analysis. Architecture alternatives.
Meticulous	Everything in Thorough + individual ADR approval, tech stack walkthrough, capacity modeling with cost estimates.

Progress Output

Follow Claude-Production-Grade-Suite/.protocols/visual-identity.md. Print structured progress throughout execution.

Skill header (print on start):

━━━ Solution Architect ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase progress (print during execution):

  [1/5] Constraint Discovery
    ✓ Scale: {users}, {CCU}, {constraints}
    ⧖ analyzing compliance requirements...
    ○ fitness function

  [2/5] Architecture Design
    ✓ Pattern: {pattern}, {N} ADRs
    ⧖ generating system diagrams...
    ○ user review

  [3/5] API Contracts
    ✓ {N} OpenAPI specs, {M} endpoints
    ⧖ defining error schemas...
    ○ versioning strategy

  [4/5] Data Model
    ✓ ERD: {N} entities, {M} migrations
    ⧖ writing migration files...
    ○ audit trail schema

  [5/5] Scaffold
    ✓ Project structure generated
    ⧖ writing Dockerfiles...
    ○ docker-compose

Completion summary (print on finish — MUST include concrete numbers):

✓ Solution Architect    {pattern}, {N} ADRs, {M} endpoints, scaffold generated    ⏱ Xm Ys

Overview

Full architecture pipeline: from business requirements to a scaffolded, production-ready codebase. The architecture is DERIVED from project constraints (scale, team, budget, compliance) — not picked from a template. There is no one-size-fits-all architecture.

Generates architecture deliverables at the project root (api/, schemas/, docs/architecture/, project scaffold) with workspace artifacts in Claude-Production-Grade-Suite/solution-architect/.

Config Paths

Read .production-grade.yaml at startup. Use these overrides if defined:

• paths.api_contracts — default: api/
• paths.adrs — default: docs/architecture/architecture-decision-records/
• paths.architecture_docs — default: docs/architecture/
• paths.erd — default: schemas/erd.md
• paths.migrations — default: schemas/migrations/
• paths.tech_stack — default: docs/architecture/tech-stack.md

Deliverables go to the project root (api/, schemas/, docs/architecture/). Workspace artifacts go to Claude-Production-Grade-Suite/solution-architect/.

When to Use

• Designing a new SaaS product or platform
• Planning microservices or service-oriented architecture
• Selecting tech stacks for production systems
• Creating API contracts and data models
• Scaffolding multi-cloud, production-grade projects
• Architecture review or modernization of existing systems

Process Flow

digraph sa {
    rankdir=TB;
    "Triggered" [shape=doublecircle];
    "Phase 1: Discovery" [shape=box];
    "Phase 2: Architecture Design" [shape=box];
    "Phase 3: Tech Stack" [shape=box];
    "Phase 4: API Contracts" [shape=box];
    "Phase 5: Data Models" [shape=box];
    "Phase 6: Scaffold" [shape=box];
    "User Review" [shape=diamond];
    "Suite Complete" [shape=doublecircle];

    "Triggered" -> "Phase 1: Discovery";
    "Phase 1: Discovery" -> "Phase 2: Architecture Design";
    "Phase 2: Architecture Design" -> "User Review";
    "User Review" -> "Phase 2: Architecture Design" [label="revise"];
    "User Review" -> "Phase 3: Tech Stack" [label="approved"];
    "Phase 3: Tech Stack" -> "Phase 4: API Contracts";
    "Phase 4: API Contracts" -> "Phase 5: Data Models";
    "Phase 5: Data Models" -> "Phase 6: Scaffold";
    "Phase 6: Scaffold" -> "Suite Complete";
}

Phase 1: Discovery & Scale Assessment

The architecture must fit the project's actual constraints. This phase gathers those constraints — at a depth matching the engagement mode.

Step 1: Read Existing Context

Before asking ANY questions, read in parallel:

1. Claude-Production-Grade-Suite/polymath/handoff/context-package.md — may contain scale, constraints, decisions
2. Claude-Production-Grade-Suite/product-manager/BRD/brd.md — user stories, acceptance criteria, business rules
3. Claude-Production-Grade-Suite/.orchestrator/codebase-context.md — brownfield context

Reduce questions to cover ONLY gaps not addressed in existing context. If polymath or PM already established scale targets, do not re-ask.

Step 2: Scale & Fitness Interview

Adapt depth to engagement mode. Use AskUserQuestion with structured options (never open-ended).

Express Mode

Skip interview entirely. Auto-derive from BRD signals:

• User count hints from user stories -> default to "small" (< 1K users) if no signals
• Tech mentions in BRD or polymath context -> use those, else conservative defaults
• Default: modular monolith, managed services, single region, single DB
• Log: ✓ Express mode — auto-deriving architecture from BRD

If a critical constraint is completely missing (e.g., BRD mentions "enterprise customers" but no scale number), ask ONE clarifying question maximum.

Standard Mode (2 rounds)

Round 1 — Scale & Users:

AskUserQuestion(questions=[{
  "question": "I need to understand your scale to design the right architecture.\n\n"
    "These 3 questions determine whether you need a simple monolith or a distributed system.",
  "header": "Scale & Users",
  "options": [
    {"label": "Small scale — < 1K users, MVP or internal tool", "description": "Simple architecture, minimal infra, fast to build"},
    {"label": "Medium scale — 1K-100K users, startup/growth", "description": "Needs to scale but not from day 1. Service extraction plan."},
    {"label": "Large scale — 100K+ users, high availability", "description": "Distributed architecture, multi-region, serious infrastructure"},
    {"label": "Not sure — help me estimate", "description": "I'll ask a few questions to figure this out"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

Follow up with:

AskUserQuestion(questions=[{
  "question": "What's the primary data pattern?",
  "header": "Data Characteristics",
  "options": [
    {"label": "Read-heavy — dashboards, content, catalogs", "description": "Cache-first, read replicas, CDN"},
    {"label": "Write-heavy — logging, IoT, transactions", "description": "Queue-based, event sourcing, eventual consistency"},
    {"label": "Balanced — typical CRUD SaaS", "description": "Standard request/response, relational DB"},
    {"label": "Real-time — chat, collaboration, live updates", "description": "WebSocket/SSE, pub/sub, in-memory state"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

Round 2 — Constraints:

AskUserQuestion(questions=[{
  "question": "Who will build and maintain this system?",
  "header": "Team & Budget",
  "options": [
    {"label": "Solo or pair — keep it simple", "description": "Monolith, managed services, minimal ops"},
    {"label": "Small team (3-5) — some specialization", "description": "Can handle moderate complexity"},
    {"label": "Medium team (6-15) — dedicated roles", "description": "Can support microservices if needed"},
    {"label": "Large team (15+) — multiple squads", "description": "Service ownership model, independent deploys"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

AskUserQuestion(questions=[{
  "question": "Any hard constraints?",
  "header": "Compliance & Deployment",
  "options": [
    {"label": "No special requirements", "description": "Standard web app, no regulatory burden"},
    {"label": "GDPR — EU user data", "description": "Data residency, right to deletion, consent management"},
    {"label": "SOC2 / ISO 27001 — enterprise customers", "description": "Audit trails, access controls, security policies"},
    {"label": "HIPAA — health data", "description": "BAA required, encryption everywhere, dedicated tenancy"},
    {"label": "PCI DSS — payment data", "description": "Tokenization, network segmentation, quarterly scans"},
    {"label": "Multiple / Other (specify)", "description": "Select to describe your requirements"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

Thorough Mode (4 rounds)

Everything in Standard, PLUS two additional rounds:

Round 3 — Technical Requirements:

AskUserQuestion(questions=[{
  "question": "Let's get precise about performance and availability requirements.",
  "header": "Performance & Availability",
  "options": [
    {"label": "Standard SaaS — 99.9% uptime, < 500ms API response", "description": "8.7 hours downtime/year. Typical for most web apps."},
    {"label": "High availability — 99.99% uptime, < 200ms response", "description": "52 minutes downtime/year. Requires multi-AZ, automated failover."},
    {"label": "Mission critical — 99.999% uptime, < 100ms response", "description": "5 minutes downtime/year. Requires multi-region, chaos engineering."},
    {"label": "Internal tool — best effort, availability not critical", "description": "Simplest architecture, no redundancy required."},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

AskUserQuestion(questions=[{
  "question": "Where are your users?",
  "header": "Geographic Distribution",
  "options": [
    {"label": "Single country", "description": "One region deployment, simplest"},
    {"label": "Single continent", "description": "One region with CDN for static assets"},
    {"label": "Global — users everywhere", "description": "Multi-region, edge CDN, data replication strategy"},
    {"label": "Not sure yet", "description": "I'll design for single-region with a multi-region migration path"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

AskUserQuestion(questions=[{
  "question": "Expected peak concurrent users (CCU)?",
  "header": "Peak Load",
  "options": [
    {"label": "< 100 CCU", "description": "Single instance can handle this"},
    {"label": "100-1K CCU", "description": "Horizontal scaling, load balancer needed"},
    {"label": "1K-10K CCU", "description": "Auto-scaling, connection pooling, caching layer"},
    {"label": "10K+ CCU", "description": "Distributed architecture, queue-buffered writes, edge computing"},
    {"label": "Help me estimate", "description": "Typically 5-10% of total users are concurrent at peak"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

Round 4 — Strategic:

AskUserQuestion(questions=[{
  "question": "How do you see this system evolving?",
  "header": "Growth & Extensibility",
  "options": [
    {"label": "Steady linear growth", "description": "Predictable scaling, plan for 10x over 2 years"},
    {"label": "Hockey stick — potential viral growth", "description": "Must handle 100x spikes, auto-scaling critical"},
    {"label": "Seasonal — predictable traffic spikes", "description": "Scale-to-zero between peaks, burst capacity"},
    {"label": "Platform play — third parties will build on this", "description": "Public API, webhooks, rate limiting, developer portal"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

AskUserQuestion(questions=[{
  "question": "Monthly infrastructure budget ceiling?",
  "header": "Budget",
  "options": [
    {"label": "Minimal — under $500/mo", "description": "Serverless, managed DBs, free tiers. Optimize for cost."},
    {"label": "Moderate — $500 to $5K/mo", "description": "Managed K8s, dedicated DBs, standard monitoring."},
    {"label": "Significant — $5K+/mo", "description": "Dedicated infra, custom observability, multi-region."},
    {"label": "Not a constraint", "description": "Optimize for performance and reliability, not cost."},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

AskUserQuestion(questions=[{
  "question": "Cloud strategy?",
  "header": "Vendor & Portability",
  "options": [
    {"label": "All-in on AWS (cheapest, most managed services)", "description": "Use AWS-native services. Fast to build, harder to migrate."},
    {"label": "All-in on GCP (best for data/ML workloads)", "description": "Use GCP-native services. Strong managed K8s."},
    {"label": "All-in on Azure (best for enterprise/Microsoft shops)", "description": "Use Azure-native services. AD integration."},
    {"label": "Cloud-agnostic (most portable, higher upfront cost)", "description": "Terraform abstractions, avoid proprietary services."},
    {"label": "Not sure — recommend based on my project", "description": "I'll recommend based on your requirements"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

Meticulous Mode

Everything in Thorough, PLUS:

• After the fitness function produces an architecture, present 2-3 alternative architectures with explicit trade-off tables (cost vs complexity vs scalability vs team fit) before the user chooses
• Individual ADR approval: present each ADR separately. User reviews and approves each decision.
• Capacity modeling: estimate infrastructure cost at current scale AND 10x projected scale
• Tech stack walkthrough: for each major tech choice, present 2-3 alternatives with rationale

Step 3: Architecture Fitness Function

After gathering inputs, DERIVE the architecture from constraints. The architecture is a FUNCTION of the inputs — not a template.

Architecture Pattern:

Scale	Team	-> Pattern
< 1K users	1-3 people	Monolith or Modular Monolith. Single deploy, single DB. Docker Compose for local dev.
1K-100K users	3-15 people	Modular Monolith with documented service boundaries. Extract services ONLY when team or scale demands. Include service extraction plan in ADR.
100K+ users	15+ people	Microservices. Service mesh, distributed data, event-driven communication. Each team owns 1-3 services.
Any scale	Solo developer	Whatever is simplest. Serverless or monolith. Managed everything. Minimize operational burden.

Infrastructure Sizing:

Budget	-> Infrastructure Strategy
< $500/mo	Serverless-first (Lambda/Cloud Run), managed DB (RDS free tier/PlanetScale), no K8s, CloudWatch/basic monitoring
$500-5K/mo	Managed K8s (EKS/GKE) or ECS, managed DB with replicas, Redis cache, standard monitoring (Grafana/Datadog)
> $5K/mo	Dedicated infrastructure, self-hosted options viable, custom observability stack, multi-region possible

Data Architecture:

Data Pattern	-> Strategy
Read-heavy (>80% reads)	Cache-first (Redis), read replicas, CDN for static, materialized views
Write-heavy	Event sourcing or CQRS, queue-buffered writes (SQS/Kafka), eventual consistency
Real-time	WebSocket/SSE infrastructure, pub/sub (Redis Pub/Sub or Kafka), in-memory state
Balanced CRUD	Standard relational DB, connection pooling, query optimization

Compliance Impact:

Requirement	-> Architecture Changes
GDPR	Data residency controls, right-to-deletion pipeline, consent management, PII encryption
SOC2 / ISO 27001	Audit trail on all mutations, RBAC, centralized logging, access review automation
HIPAA	Dedicated tenancy, encryption at rest + transit, BAA with all vendors, audit logging, no shared infrastructure
PCI DSS	Tokenize card data (use Stripe/Adyen), network segmentation, quarterly vulnerability scans, no raw card storage

Availability Impact:

SLA	-> Architecture Changes
99% (3.7 days/yr)	Single instance OK, basic health checks
99.9% (8.7 hrs/yr)	Multi-AZ, load balancer, automated restarts, basic monitoring
99.99% (52 min/yr)	Multi-AZ with automated failover, zero-downtime deploys, chaos engineering, comprehensive monitoring
99.999% (5 min/yr)	Multi-region active-active, global load balancing, circuit breakers everywhere, dedicated SRE

Growth Model Impact:

Growth	-> Architecture Changes
Linear/steady	Plan for 10x. Vertical scaling first, horizontal when needed.
Hockey stick	Horizontal scaling from day 1. Stateless services. Auto-scaling groups. Queue-buffered writes. Feature flags for load shedding.
Seasonal	Scale-to-zero capable (serverless/spot instances). Pre-warming automation. Burst capacity planning.
Platform/API	API gateway, rate limiting, webhook system, developer portal, backwards-compatible versioning from day 1.

Present the derived architecture: "Based on your constraints [summary], here's what fits and why..."

For Thorough/Meticulous modes, also present 1-2 alternative architectures:

• Conservative alternative: simpler, faster to build, may need rework at scale
• Ambitious alternative: handles more future growth, higher upfront complexity and cost

Each alternative includes a trade-off summary: build time, operational complexity, monthly cost estimate, scaling ceiling, team fit.

Phase 2: Architecture Design

Generate architecture documents in docs/architecture/ (or paths.architecture_docs from config):

architecture-decision-records/

One ADR per major decision using this template:

# ADR-NNN: [Title]
**Status:** Accepted | Superseded | Deprecated
**Context:** Why this decision is needed
**Decision:** What we chose and why
**Consequences:** Trade-offs accepted
**Alternatives Considered:** What we rejected and why

Required ADRs:

• Architecture pattern (monolith, microservices, modular monolith, event-driven)
• Communication patterns (sync REST/gRPC, async messaging, CQRS)
• Data strategy (shared DB, DB-per-service, event sourcing)
• Auth architecture (JWT, OAuth2, session-based)
• Multi-tenancy strategy (row-level, schema-level, DB-level)

system-diagrams/

Create Mermaid diagrams in markdown files:

• C4 Context — system boundaries and external actors
• C4 Container — services, databases, message brokers, CDN
• Sequence diagrams — for critical user flows (auth, payment, data pipeline)
• Infrastructure topology — cloud resources and networking

Design Principles

Apply and document these production patterns:

• 12-Factor App methodology
• Defense in depth (security layers)
• Circuit breaker, retry, timeout patterns
• Idempotency for all write operations
• Eventual consistency where appropriate
• Zero-trust networking

Present architecture to user via AskUserQuestion for approval before proceeding.

Phase 3: Tech Stack Selection

Generate docs/architecture/tech-stack.md (or paths.tech_stack from config):

Layer	Selection	Rationale
Language(s)	Based on team/requirements	Performance, ecosystem, hiring
Framework	Based on language choice	Maturity, community, features
Database(s)	Based on data patterns	ACID vs BASE, query patterns
Cache	Redis/Memcached	Access patterns, consistency needs
Message Broker	Kafka/RabbitMQ/SQS/Pub-Sub	Throughput, ordering, durability
API Gateway	Kong/AWS API GW/GCP API GW	Rate limiting, auth, routing
Auth	Keycloak/Auth0/Cognito/Firebase Auth	SSO, MFA, compliance
Search	Elasticsearch/OpenSearch	Full-text, analytics, scale
Object Storage	S3/GCS/Azure Blob	Cost, lifecycle, CDN integration
CDN	CloudFront/Cloud CDN/Azure CDN	Edge locations, cost

Selection criteria: production maturity, multi-cloud portability, team expertise, cost at scale.

Phase 4: API Contract Design

Generate API contracts at api/ (or paths.api_contracts from config) at the project root:

• OpenAPI 3.1 specs for REST APIs — complete with request/response schemas, auth, error codes
• gRPC proto files if inter-service communication is gRPC
• AsyncAPI specs for event-driven interfaces
• API versioning strategy documented (URL path vs header)

Standards enforced:

• Consistent error response format ({code, message, details, trace_id})
• Pagination (cursor-based for production, offset only for admin)
• Rate limiting headers (X-RateLimit-*)
• HATEOAS links where appropriate
• Request ID propagation (X-Request-ID)

Phase 5: Data Model Design

Generate data models at schemas/ at the project root:

• ERD diagrams in Mermaid (at paths.erd from config, default schemas/erd.md)
• SQL migration files (numbered, idempotent) (at paths.migrations from config, default schemas/migrations/)
• NoSQL collection schemas (if applicable)
• Data flow diagrams — showing how data moves between services
• Audit trail schema — who changed what, when

Standards enforced:

• Soft deletes with deleted_at timestamps
• UUID primary keys (not auto-increment) for distributed systems
• Created/updated timestamps on all entities
• Tenant isolation at the data layer
• PII field identification and encryption strategy

Phase 6: Project Scaffolding

Scaffold the project root structure directly. The scaffold IS the project root — there is no separate scaffold directory.

project root/
├── services/
│   └── <service-name>/
│       ├── src/
│       ├── tests/
│       ├── Dockerfile
│       ├── Makefile
│       └── README.md
├── libs/
│   └── shared/          # Shared types, utils, clients
├── docker-compose.yml   # Local dev environment
├── Makefile             # Root-level commands
└── README.md            # Getting started guide

Each service includes:

• Health check endpoint (/healthz, /readyz)
• Structured logging (JSON, correlation IDs)
• Graceful shutdown handling
• Configuration from environment variables
• Basic test structure (unit, integration)
• Dockerfile (multi-stage, non-root user, minimal base image)

Output Structure

Project Root Output (Deliverables)

docs/architecture/
│   ├── architecture-decision-records/
│   │   ├── ADR-001-architecture-pattern.md
│   │   └── ...
│   ├── system-diagrams/
│   │   ├── c4-context.md
│   │   ├── c4-container.md
│   │   └── sequence-*.md
│   ├── tech-stack.md
│   └── design-principles.md
api/
│   ├── openapi/
│   │   └── *.yaml
│   ├── grpc/
│   │   └── *.proto
│   └── asyncapi/
│       └── *.yaml
schemas/
│   ├── erd.md
│   ├── migrations/
│   │   └── *.sql
│   └── data-flow.md
services/                          # Scaffolded service directories
│   └── <service-name>/
│       ├── src/
│       ├── tests/
│       ├── Dockerfile
│       └── Makefile
libs/shared/
docker-compose.yml
Makefile
README.md

Workspace Output (Claude-Production-Grade-Suite/solution-architect/)

Claude-Production-Grade-Suite/solution-architect/
├── working-notes.md
└── analysis/
    └── *.md

Cloud-Specific Patterns

AWS

• ECS/EKS for orchestration, RDS/Aurora for relational, DynamoDB for key-value
• SQS/SNS for messaging, CloudWatch for monitoring, Secrets Manager
• VPC with public/private subnets, NAT Gateway, ALB

GCP

• GKE/Cloud Run for orchestration, Cloud SQL/Spanner for relational, Firestore for document
• Pub/Sub for messaging, Cloud Monitoring, Secret Manager
• VPC with private service access, Cloud Load Balancing

Azure

• AKS/Container Apps for orchestration, Azure SQL/Cosmos DB for data
• Service Bus for messaging, Azure Monitor, Key Vault
• VNet with subnets, Application Gateway, Front Door

Multi-Cloud Abstractions

• Use Terraform modules with provider-agnostic interfaces
• Abstract cloud-specific SDKs behind service interfaces
• Document cloud provider mapping in tech-stack.md

Common Mistakes

Mistake	Fix
Picking architecture before knowing constraints	Run the fitness function FIRST. Scale, team, budget determine the pattern.
Microservices for a 2-person team	Start modular monolith, extract services when team/scale demands
Kubernetes for < 1K users	Docker Compose or serverless. K8s operational cost > benefit at small scale.
Same architecture for $200/mo and $20K/mo	Budget changes everything — serverless vs dedicated, managed vs self-hosted
Shared database across services	Each service owns its data, communicate via APIs/events
No API versioning strategy	Decide v1 URL path versioning from day one
Skipping ADRs	Future-you needs to know WHY, not just WHAT
Over-engineering auth	Use managed auth (Auth0/Cognito) unless compliance requires self-hosted
Ignoring multi-tenancy from start	Retrofitting tenant isolation is 10x harder than designing it in
Skipping scale interview	"Build a SaaS" means nothing without scale context. 100 users vs 10M users is a completely different system.
Ignoring engagement mode	Express: auto-derive. Standard: 2 rounds. Thorough: 4 rounds. Meticulous: full walkthrough. Read settings.md.
Designing for 10M users when there are 100	Design for current + 10x. Not 1000x. Over-engineering kills velocity.
Not presenting alternatives in Thorough/Meticulous	Users at those engagement levels want to understand trade-offs, not just see one answer.