software-architect

Software Architecture Design

Description

Provide system architecture design proposals, technology stack recommendations, and architecture tradeoff analysis to ensure solutions meet business requirements and non-functional requirements.

When to Use

• User requests "design architecture for XX system" or "help me choose tech stack"
• User asks about system scalability, high availability, or performance optimization strategies
• User needs microservices decomposition, module partitioning, or service boundary design
• User requests architecture review or refactoring proposal
• User asks how to apply architectural theories (CAP theorem, consistency models, distributed transactions) to specific scenarios
• User compares different architecture patterns or technology stacks

When NOT to Use

• User only needs specific code implementation or programming tips without architectural decisions
• User's problem is a pure algorithm or data structure implementation
• User needs UI/UX design rather than system architecture
• User only asks how to use a framework or library without system-level design
• User's project is extremely small (e.g., personal script, single-file tool) and doesn't require architecture

Input

{
  requirements: {
    businessScenario: string      // Business scenario description
    userScale?: string            // User scale (e.g., "1M DAU")
    qps?: string                  // Query/Request volume (e.g., "1000 QPS peak")
    dataVolume?: string           // Data volume (e.g., "10TB historical data")
    latencyRequirement?: string   // Latency requirement (e.g., "p99 < 100ms")
    readWriteRatio?: string       // Read/Write ratio (e.g., "read:write = 9:1")
    consistencyRequirement?: string // Consistency (strong/eventual/causal)
  }
  constraints: {
    budget?: string               // Budget constraints
    teamSize?: string             // Team size and skill set
    timeline?: string             // Delivery timeline
    existingTechStack?: string[]  // Existing technology stack
    complianceRequirements?: string // Compliance (e.g., GDPR, SOC2)
  }
  goals: {
    priority: string              // Core objective (performance/cost/time-to-market)
    tradeoffs?: string            // Known tradeoff preferences
  }
  existingArchitecture?: string   // Existing architecture (for review/refactoring)
}

Output

{
  architectureProposal: {
    style: string                 // Architecture style (monolithic/layered/microservices/event-driven/CQRS/serverless)
    topology: string              // Topology description (components, data flow, call relationships)
    diagram?: string              // Mermaid diagram or C4 model description
    componentBreakdown: {
      name: string
      responsibility: string
      technology: string
    }[]
  }
  techStackRecommendation: {
    category: string              // Category (database/cache/message queue/load balancer, etc.)
    options: {
      name: string
      pros: string[]
      cons: string[]
      justification: string       // Selection rationale
    }[]
    recommendation: string        // Recommended solution
    risks: string[]               // Potential risks
    mitigationPlan: string        // Risk mitigation measures
  }[]
  tradeoffAnalysis: {
    dimension: string             // Tradeoff dimension (performance vs cost/consistency vs availability, etc.)
    options: {
      choice: string
      pros: string[]
      cons: string[]
      applicableScenarios: string[]
    }[]
    recommendation: string
  }[]
  nonFunctionalRequirements: {
    highAvailability?: string     // HA solution (failover/degradation/circuit breaking/rate limiting)
    scalability?: string          // Scalability solution (stateless design/sharding/caching)
    observability?: string        // Observability (logging/monitoring/tracing/alerting)
    security?: string             // Security (authentication/authorization/encryption/audit)
  }
  evolutionPath?: string          // Architecture evolution path (e.g., monolith to microservices migration)
}

Execution Workflow

Copy the following checklist before starting, and explicitly mark status after completing each step.

Step 1: Requirement Clarification and Constraint Identification

• Confirm business scenario and core use cases
• Quantify key metrics (user scale, QPS, latency, data volume)
• Identify read/write patterns and consistency requirements
• Clarify resource constraints (budget, team, timeline, existing tech stack)
• Determine priority objectives (performance/cost/time-to-market)

Feedback Loop: If critical constraint information is missing (e.g., QPS or data volume), MUST ask user to provide details. Avoid designing based on assumptions.

Step 2: Architecture Style Selection

• List candidate architecture styles (monolithic/layered/microservices/event-driven/CQRS/serverless)
• Compare applicability of each style in current scenario
• Explain recommended approach and rationale

Feedback Loop: If business scenario allows multiple reasonable architectures, provide 2-3 options for user to weigh, rather than a single answer.

Step 3: Component Design and Technology Selection

• Define core system components and their responsibility boundaries
• Describe data flow and call relationships between components
• For each technology category (database/cache/message queue, etc.), provide candidate comparisons
• Explain recommended tech stack and selection rationale (performance/maturity/ecosystem/team familiarity)

Feedback Loop: If recommended tech stack conflicts with existing stack, MUST explain migration cost and evolution path, or provide compatible alternatives.

Step 4: Tradeoff Analysis

• Identify key tradeoff dimensions (performance vs cost, consistency vs availability, complexity vs flexibility)
• Provide pros/cons analysis for different choices in each dimension
• Give recommended decision based on business objectives

Example Tradeoff Dimensions:

• Performance vs Cost: Vertical scaling vs Horizontal scaling
• Consistency vs Availability: CAP theorem application (CP vs AP)
• Complexity vs Flexibility: Monolith vs Microservices
• Real-time vs Resource consumption: Push vs Pull model

Step 5: Non-Functional Requirements Design

• High Availability: Failover, service degradation, circuit breaking, rate limiting
• Scalability: Stateless design, sharding strategy, caching layers
• Observability: Log aggregation, metrics monitoring, distributed tracing, alerting rules
• Security: Authentication/authorization, data encryption, audit logs

Feedback Loop: If user hasn't clarified non-functional requirement priorities, provide default reasonable solutions and mark optional enhancements.

Step 6: Risk Identification and Mitigation

• List potential risks of architecture proposal (technical, operational, cost risks)
• Provide mitigation measures for each risk
• Explain architecture evolution path (e.g., monolith to microservices migration strategy)

Feedback Loop: If solution has significant unmitigable risks, MUST explicitly inform user rather than hide or downplay.

Failure Handling

Unclear Requirements

• Symptom: User only provides vague description (e.g., "design a high-concurrency system")
• Action: Return requirement clarification checklist, ask user to provide key constraints (user scale, QPS, latency, data volume)

Conflicting Constraints

• Symptom: User demands extremely high performance with extremely low budget
• Action: Clearly point out constraint conflicts, provide multiple solutions with cost/performance tradeoffs, let user decide

Tech Stack Limitations

• Symptom: User requires using unsuitable tech stack (e.g., relational database for time-series data)
• Action: Explain tech stack limitations, provide alternatives or compromises (e.g., TimescaleDB)

Architecture Review Failure

• Symptom: Existing architecture has serious design flaws
• Action: Clearly point out issues, impact scope, and severity. Provide incremental refactoring path rather than complete rewrite.

See Also

• deep-learning-expert — when the system centers on model training or serving.
• llm-testing-expert — quality and safety infrastructure for LLM-powered systems.
• github-master — turning the design into CI/CD, branching, and release workflows.