Architecture Advisor

Architecture Advisor

Evaluates project requirements to recommend the best architecture for solo developers working with AI agents

When to Use

• Starting a new project and unsure which architecture to choose
• Reconsidering architecture of an existing project
• Need justification for architectural decisions
• Want to understand trade-offs for your specific situation
• Planning future extraction from monolith to microservices

When NOT to Use

• Already have a team of 5+ developers (traditional frameworks apply)
• Need detailed system design (this is high-level architecture only)
• Looking for technology/framework recommendations (separate concern)

Orchestrator

This skill coordinates the following sub_agents:

Workflows

Primary: Evaluate Architecture

Path: workflows/evaluate-architecture.md

Full evaluation workflow:

1. Collect Inputs → Gather project info, scale, constraints
2. Analyze Factors → Score against decision framework
3. Generate Recommendation → Determine best fit with confidence
4. Build Rationale → Create personalized explanation
5. Present Report → Formatted decision document

Context Integration

Target User Profile

• Solo developer (team of 1)
• Uses AI agents for development (Claude, Copilot, Cursor, etc.)
• Needs architecture they can maintain alone with AI assistance

Key Insight

Traditional architecture decision frameworks assume teams. This skill is calibrated for the reality of one person + AI agents, where:

• Operational simplicity beats theoretical scalability
• AI works better with full codebase context (favors monoliths)
• Deployment complexity directly impacts development velocity

Commands

/architecture-advisor

Run full architecture evaluation workflow.

Usage:

/architecture-advisor
> Answer questions about your project
> Receive recommendation with rationale

/architecture-advisor:quick "<description>"

Quick evaluation with sensible defaults.

Usage:

/architecture-advisor:quick "e-commerce site, 5K users, bootstrap budget"

Implementation

Entry Point Logic

When /architecture-advisor is invoked:

1. Initialize evaluation state
2. Run input-collector sub-agent
3. Run factor-analyzer on collected inputs
4. Run recommendation-engine on analysis
5. Run rationale-generator on recommendation
6. Format and present final report

State Management

state:
  project_input: null | ProjectInput
  factor_analysis: null | FactorAnalysis
  recommendation: null | Recommendation
  rationale: null | Rationale

Decision Framework

Factors and Weights (Solo Developer Calibration)

Score Calculation

def calculate_architecture_scores(inputs):
    factors = [
        ('team_size', 0.25, evaluate_team_size),
        ('ai_friendliness', 0.20, evaluate_ai_fit),
        ('deployment', 0.15, evaluate_deployment),
        ('debugging', 0.15, evaluate_debugging),
        ('scale', 0.10, evaluate_scale),
        ('domain', 0.10, evaluate_domain),
        ('flexibility', 0.05, evaluate_flexibility),
    ]

    scores = {'monolith': 0, 'microservices': 0, 'hybrid': 0}

    for name, weight, evaluator in factors:
        factor_scores = evaluator(inputs)
        for arch in scores:
            scores[arch] += weight * factor_scores[arch]

    return scores

Factor Evaluation Details

Team Size (25%)

Solo developer always favors monolith

Rationale: One person cannot effectively manage distributed system operations. This is the strongest signal.

AI-Friendliness (20%)

AI tools work best with full codebase context

Rationale: Claude/Copilot can see entire monolith; microservices fragment context.

Deployment Simplicity (15%)

Solo devs need simple deployments

Rationale: Microservices require K8s, service mesh, etc.—too much for one person.

Debugging Ease (15%)

Stack traces beat distributed tracing for solo devs

Expected Scale (10%)

Scale threshold for microservices is high

Rationale: Microservices overhead only justified at significant scale.

Domain Complexity (10%)

Clear boundaries might justify extraction later

Future Flexibility (5%)

Plan for success, but don't over-engineer

Architecture Variants

Monolith Variants

Hybrid Variants

Hard Rules (Override Scores)

These conditions override calculated scores:

Output Format

╔══════════════════════════════════════════════════════════════╗
║  Architecture Recommendation: {PROJECT_NAME}                  ║
╠══════════════════════════════════════════════════════════════╣

📋 RECOMMENDATION: {ARCHITECTURE} ({VARIANT})
   Confidence: {SCORE}%

📝 SUMMARY
   {Personalized 2-3 sentence summary}

✅ WHY THIS FITS YOUR SITUATION
   • {Dominant factor 1}
   • {Dominant factor 2}
   • {Dominant factor 3}

👍 PROS (Solo Developer Context)
   • {Pro}: {How it helps you specifically}

⚠️  CONS (With Mitigations)
   • {Con}: {How to address it}

🤖 AI AGENT CONSIDERATIONS
   • {How architecture affects AI tool effectiveness}

🔄 ALTERNATIVE: {ALT_ARCHITECTURE}
   Consider if: {Trigger conditions}

📌 NEXT STEPS
   1. {Immediate action}
   2. {Setup action}
   3. {Documentation action}

╚══════════════════════════════════════════════════════════════╝

Common Recommendations

90%+ of Solo Projects: Modular Monolith

recommendation: modular-monolith
confidence: 0.85
summary: >
  For most solo developers with AI agents, a modular monolith
  provides the best balance of simplicity and future flexibility.
  AI tools work effectively with full codebase context, deployment
  is simple, and you can extract services later if needed.

next_steps:
  - Design clear module boundaries based on domain concepts
  - Set up single deployment (Vercel, Railway, Fly.io)
  - Create CLAUDE.md documenting patterns for AI assistants
  - Implement feature flags for safe deployments
  - Add monitoring to detect when extraction might help

When Hybrid Makes Sense

triggers:
  - Specific component with 10x higher load than others
  - Real-time requirements (chat, live updates) alongside CRUD
  - Third-party integration that benefits from isolation

recommendation: hybrid
variant: monolith-plus-service
next_steps:
  - Keep core business logic in monolith
  - Extract only the specific high-load/real-time component
  - Use simple service communication (HTTP, not message queues)
  - Share authentication between monolith and service

Rare: When Microservices Might Apply

triggers:
  - Proven scale >1M users (not projected)
  - Advanced DevOps experience
  - Multiple clearly independent products
  - Team growth imminent

recommendation: microservices
warning: >
  Even with these triggers, consider starting with modular monolith
  and extracting. Microservices add significant operational burden
  that's hard to manage solo.

Example Evaluations

Example 1: Indie SaaS Product

Input:

project:
  name: "TaskFlow"
  description: "Project management tool for freelancers"
  platforms: [web]
  domain: "productivity-saas"
scale:
  expected_users: 5000
  expected_growth: "moderate"
solo_context:
  ai_tools_used: [claude, cursor]
  development_style: "ai-first"
  devops_comfort: "intermediate"
constraints:
  time_to_mvp: "3 months"
  budget: "bootstrap"

Analysis:

Team Size (25%):     Monolith: 100 | Microservices: 10 | Hybrid: 50
AI-Friendliness (20%): Monolith: 90 | Microservices: 40 | Hybrid: 70
Deployment (15%):    Monolith: 90 | Microservices: 40 | Hybrid: 65
Debugging (15%):     Monolith: 85 | Microservices: 45 | Hybrid: 70
Scale (10%):         Monolith: 95 | Microservices: 30 | Hybrid: 50
Domain (10%):        Monolith: 95 | Microservices: 30 | Hybrid: 50
Flexibility (5%):    Monolith: 90 | Microservices: 30 | Hybrid: 60
─────────────────────────────────────────────────────────────────
TOTAL:               Monolith: 92 | Microservices: 31 | Hybrid: 59

Recommendation: modular-monolith (Confidence: 92%)

Example 2: Real-Time Collaboration Tool

Input:

project:
  name: "CollabDocs"
  description: "Real-time document editing with AI assistance"
  platforms: [web, desktop]
  domain: "collaboration"
scale:
  expected_users: 50000
  real_time_requirements: true
solo_context:
  ai_tools_used: [claude]
  development_style: "ai-assisted"
  devops_comfort: "intermediate"
constraints:
  time_to_mvp: "6 months"
  budget: "moderate"

Recommendation: monolith-plus-realtime (Hybrid, Confidence: 78%)

Rationale: Real-time collaboration (WebSocket connections) benefits from a dedicated service, while core document CRUD stays in monolith. This keeps most code in full AI context while isolating the scaling-sensitive real-time component.

Example 3: E-Commerce Platform

Input:

project:
  name: "ArtisanMarket"
  description: "Marketplace for handmade goods"
  platforms: [web, ios, android]
  domain: "e-commerce"
scale:
  expected_users: 100000
  expected_growth: "aggressive"
solo_context:
  ai_tools_used: [claude, copilot]
  development_style: "ai-first"
  devops_comfort: "advanced"
constraints:
  time_to_mvp: "4 months"
  budget: "moderate"
  compliance: ["PCI-DSS"]

Recommendation: api-first-monolith (Confidence: 75%)

Rationale: Multiple platforms require clean API boundaries. Even with aggressive growth expectations, start monolithic with API-first design. Extract payment processing to separate service only if PCI compliance scope reduction is needed.

Input Collection

Questions gathered by input-collector sub-agent:

1. Project identity (name, description, platforms, domain)
2. Scale expectations (users, growth, real-time needs)
3. Solo context (AI tools, development style, DevOps comfort)
4. Constraints (timeline, budget, compliance)

See sub_agents/input-collector.md for detailed question flow.

Error Handling

Input Validation Errors

Analysis Errors

Output Errors

Technology Stack Suggestions

Based on architecture recommendation, suggest stacks optimized for solo + AI development:

Monolith Stacks

Hybrid Stacks

Research Basis

This decision framework is based on:

• 2025 industry consensus: Below 10 devs, monoliths perform better
• Amazon Prime Video case: Cut costs 90% returning to monolith
• AI-first development patterns: Simple architectures work best with AI
• Solo AI startup best practices: Solo founders can build at scale with right architecture

Configuration

Orchestrator Agent

This skill has an associated orchestrator agent at .claude/agents/architecture-advisor.md that coordinates the sub-agents. The orchestrator:

• Runs input-collector to gather project requirements
• Runs factor-analyzer with solo-developer calibrated weights
• Runs recommendation-engine to determine best architecture
• Runs rationale-generator for personalized explanation

References

• references/CONTEXT.md - Enhanced context for this skill
• references/RESEARCH.md - Research findings and sources
• sub_agents/*.md - Sub-agent documentation
• workflows/*.md - Workflow definitions