Generate and compare multiple architecture options (minimal, moderate, full modernization) with comprehensive trade-offs analysis across cost, timeline, risk, performance, and maintainability dimensions. Use when evaluating multiple architectural approaches or deciding between modernization strategies with different cost/risk trade-offs.
Generate and compare multiple architecture options (minimal, moderate, full modernization) with comprehensive trade-offs analysis across cost, timeline, risk, performance, and maintainability dimensions. Use when evaluating multiple architectural approaches or deciding between modernization strategies with different cost/risk trade-offs.
acceptance
[{"three_options_generated":"Three distinct architecture options created (minimal, moderate, full)"},{"trade_offs_analyzed":"Each option includes cost, timeline, risk, performance, maintainability analysis"},{"recommendation_provided":"Clear recommendation based on user constraints with justification"},{"comparison_matrix":"Side-by-side comparison matrix for easy evaluation"},{"next_steps_defined":"Implementation roadmap outlined for recommended option"}]
inputs
{"current_architecture":{"type":"string","required":false,"description":"Path to current architecture document or textual description of existing system"},"new_requirements":{"type":"string","required":true,"description":"User's goals, ideas, and new requirements to be incorporated"},"constraints":{"type":"object","required":false,"description":"Timeline, budget, team size, expertise constraints","default":{}},"comparison_dimensions":{"type":"array","required":false,"description":"Dimensions to compare (cost, timeline, risk, performance, maintainability, scalability, security)","default":["cost","timeline","risk","maintainability"]},"project_type":{"type":"string","required":false,"description":"frontend | backend | fullstack (auto-detected if not provided)"}}
outputs
{"comparison_created":{"type":"boolean","description":"Whether comparison document was successfully created"},"comparison_location":{"type":"string","description":"File path to comparison document (docs/architecture-comparison-{timestamp}.md)"},"options_count":{"type":"number","description":"Number of architecture options generated (always 3)"},"recommended_option":{"type":"string","description":"Which option is recommended (minimal | moderate | full)"},"recommendation_confidence":{"type":"number","description":"Confidence in recommendation (0-100)"}}
Generate three distinct architecture options with comprehensive trade-offs analysis to help users make informed decisions about system modernization or design. Each option represents a different investment level (minimal, moderate, full) with detailed cost, timeline, risk, and quality analysis.
Core Principles:
Present 3 viable options (not 1 perfect solution)
Honest trade-offs analysis (no "best" option without context)
Evidence-based estimates (cost, timeline, risk)
Clear recommendation with justification
Actionable next steps for chosen option
Prerequisites
Understanding of current system (if brownfield)
Clear new requirements or goals
User constraints known (timeline, budget, team)
workspace/ directory exists for output storage
Workflow
Step 1: Analyze Current State & Requirements
Action: Understand current architecture and new requirements to create meaningful options.
Key Activities:
Load Current Architecture (if brownfield)
# If current_architecture path provided
python .claude/skills/bmad-commands/scripts/read_file.py \
--path {current_architecture} \
--output json
# Extract:# - Current technology stack# - Architecture patterns# - Known limitations/pain points# - Production readiness score (if from analyze-architecture)
If current architecture is textual description, parse for:
Business goals: Why these changes matter, expected outcomes
Success criteria: How to measure success
Example parsing:
Input: "Add real-time chat, support 10K concurrent users, mobile app needed"
Parsed:
- Functional: Real-time chat feature, mobile support
- Non-functional: Scale to 10K concurrent (performance requirement)
- Technical implications: Need WebSocket/SSE, mobile framework
Identify Constraints
From constraints parameter:
Timeline: How soon is this needed? (weeks, months, year)
Budget: Cost sensitivity (low, moderate, high)
Team size: How many developers available?
Team expertise: Current skill set, willingness to learn new tech
Risk tolerance: Conservative (low risk) vs. aggressive (innovation)
Default assumptions if not provided:
Timeline: Moderate (3-6 months)
Budget: Moderate
Team: Small (2-5 developers)
Expertise: Moderate (willing to learn)
Risk tolerance: Moderate
Detect Project Type (if not provided)
Based on current architecture and requirements:
Frontend: UI/UX dominant, client-side changes
Backend: API/services/data dominant
Fullstack: Both frontend and backend changes
Output: Comprehensive context for option generation
See:references/requirement-analysis.md for detailed parsing techniques
Step 2: Generate Three Architecture Options
Action: Create three distinct options representing different investment/change levels.
Option Generation Strategy:
Option A: Minimal Changes (Lowest Risk, Fastest)
Philosophy: Keep what works, fix what's broken, add minimally.
Approach:
Technology: Stick with current stack, upgrade versions
Migration: Phased complete migration or parallel run
Typical Characteristics:
Timeline: 4-8 months
Cost: $$$ (4-6x baseline)
Risk: High (major changes, new tech, migration complexity)
Team impact: Significant learning (new ecosystem)
Technical debt: Near zero (clean slate)
Example (Real-time Chat Requirement):
## Option C: Full Modernization - Real-time First Architecture**Approach:** Rebuild as real-time-first app with modern fullstack framework.
**Technology Stack:**- Frontend: Next.js 15 (React 19, server components)
- Backend: tRPC + WebSocket, serverless functions
- Database: PostgreSQL (main) + Redis (cache/pub-sub)
- Real-time: Ably or Pusher (managed real-time infrastructure)
- Mobile: React Native (shared components with web)
**Architecture:**- Fullstack monorepo (Turborepo)
- Real-time-first design (WebSocket primary, HTTP fallback)
- Serverless functions (auto-scaling)
- CDN edge functions for global performance
- Mobile + web from single codebase
**Changes Required:**- Complete rebuild of frontend in Next.js (~8K LOC)
- Backend as tRPC API + WebSocket (~4K LOC)
- Real-time infrastructure setup (Ably/Pusher)
- Mobile app (React Native, ~3K LOC)
- Data migration from old to new system
**Pros:**
✅ Modern, maintainable codebase
✅ Excellent real-time performance
✅ Scales to 100K+ users easily
✅ Mobile + web unified
✅ Easy to hire developers (popular stack)
✅ Near-zero technical debt
**Cons:**
❌ Long timeline (4-6 months)
❌ High cost (significant investment)
❌ Team needs to learn new stack
❌ Complex migration from old system
❌ Risk of over-engineering
**Cost:** $120K-$180K (developer time + services)
**Timeline:** 4-6 months
**Risk:** High
Step 3: Perform Trade-offs Analysis
Action: Compare options across key dimensions to enable informed decision.
Key Dimensions:
1. Cost Analysis
Components:
Development time: Developer hours × hourly rate
Infrastructure: Hosting, services, licenses
Migration: Data migration, parallel running, cutover
## My Recommendation: Option B - Moderate Refactor**Confidence:** 85% (High)
**Why This Option:**
Given the constraints:
- Timeline: 3-4 months (moderate)
- Budget: $40K-$60K (moderate)
- Risk tolerance: Medium (willing to invest strategically)
- Priorities: Scale for growth + reduce technical debt
**Option B (Moderate Refactor) is the best fit because:**1.**Balanced Investment:** - Not too fast/cheap (Option A would hit limits soon)
- Not too slow/expensive (Option C might be over-engineering)
- $40K-$60K is reasonable for 2-3 month project
2.**Addresses Core Needs:** - Solves real-time chat requirement properly (dedicated service)
- Scales to 25K users (covers the 10K + growth trajectory)
- Sets up for future microservices (if needed)
3.**Manageable Risk:** - Team can learn gradually (not all at once like Option C)
- Incremental migration (lower risk than big bang)
- Proven patterns (microservices, event-driven)
4.**Future-Proof:** - Reduces technical debt (20% improvement)
- Easier to hire (modern but not bleeding edge)
- Positions for growth (can add more services later)
**When to Consider Alternatives:**-**Choose Option A if:** Timeline is critical (<6 weeks), budget is very tight (<$30K)
-**Choose Option C if:** Planning for 100K+ users, have 6+ months, budget >$120K
Confidence Scoring:
High (80-100%): Clear constraints, obvious best choice
Medium (60-79%): Trade-offs close, depends on priorities
Low (<60%): Need more information, similar options
Step 5: Create Comparison Document
Action: Generate comprehensive comparison document with all options, trade-offs, and recommendation.
Document Structure:
# Architecture Options Comparison: [Project Name]**Date:** [YYYY-MM-DD]
**Prepared For:** [User/Stakeholder]
**Current State:** [Brief summary of existing architecture]
**New Requirements:** [What's being added/changed]
---
## Executive Summary**Recommendation:** Option B - Moderate Refactor
**Confidence:** 85% (High)
**Why:** Balanced approach that meets the requirements, fits timeline/budget, and positions for future growth without over-engineering.
**Quick Comparison:**
| Factor | Option A | Option B ✅ | Option C |
|--------|----------|------------|----------|
| **Timeline** | 3-4 weeks | 2-3 months | 4-6 months |
| **Cost** | $15K-$25K | $40K-$60K | $120K-$180K |
| **Risk** | Low (18) | Medium (43) | High (66) |
| **Scale** | ~5K users | ~25K users | ~100K+ users |
| **Tech Debt** | +10% | -20% | -90% |
---
## Option A: Minimal Changes
[Detailed description from Step 2]
**Architecture Diagram:**
[ASCII or reference to diagram]
**Technology Stack:**- [List with justifications]
**Implementation Plan:**1. [High-level steps]
2. ...
**Pros & Cons:**
✅ [Pros]
❌ [Cons]
**Trade-offs Analysis:**
[Cost, timeline, risk, performance, maintainability details]
---
## Option B: Moderate Refactor ✅ RECOMMENDED
[Detailed description from Step 2]
[Same sections as Option A]
**Why This is Recommended:**
[Recommendation justification from Step 4]
---
## Option C: Full Modernization
[Detailed description from Step 2]
[Same sections as Option A]
---
## Side-by-Side Comparison### Cost Comparison
[Detailed cost breakdown table]
### Timeline Comparison
[Gantt chart or timeline visualization]
### Risk Comparison
[Risk matrix or scoring table]
### Performance Comparison
[Performance metrics table]
### Maintainability Comparison
[Technical debt and code quality comparison]
---
## Recommendation Details### Primary Recommendation: Option B
[Full justification from Step 4]
### Alternative Scenarios**If timeline is critical (<6 weeks):**
→ Choose Option A, plan for Option B later
**If budget is generous (>$120K):**
→ Consider Option C for long-term investment
**If team is risk-averse:**
→ Start with Option A, evaluate results, then consider Option B
---
## Next Steps### If You Choose Option A (Minimal):1. [Implementation roadmap]
2. [Key decisions needed]
3. [Timeline with milestones]
### If You Choose Option B (Moderate) ✅:1.**Week 1-2:** Architecture design finalization
2.**Week 3-4:** Chat microservice development
3.**Week 5-6:** API gateway setup + integration
4.**Week 7-8:** Frontend integration + testing
5.**Week 9-10:** Migration + stabilization
**Key Decisions Needed:**- Message bus choice (RabbitMQ vs. Kafka vs. AWS SQS)
- API gateway (Kong vs. Express Gateway vs. AWS API Gateway)
- MongoDB hosting (self-managed vs. MongoDB Atlas)
**Success Criteria:**- Chat supports 10K concurrent users
- p95 latency <100ms
- Zero downtime migration
- No data loss during migration
### If You Choose Option C (Full):1. [Implementation roadmap]
2. [Key decisions needed]
3. [Timeline with milestones]
---
## Appendices### Appendix A: Assumptions- [List all assumptions made]
### Appendix B: Technology Comparison- [Detailed tech stack comparison]
### Appendix C: Migration Strategy- [For Option B and C, detailed migration approach]
### Appendix D: Risk Mitigation- [For each identified risk, mitigation strategies]
---
**Prepared by:** Winston (Architecture Subagent)
**Review Status:** Ready for Stakeholder Review
**Next Action:** Decision on preferred option
