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:

| Sub-Agent | Purpose | Invoked During | |-----------|---------|----------------| | input-collector | Gathers project requirements via structured questions | Step 1 | | factor-analyzer | Evaluates inputs against weighted decision criteria | Step 2 | | recommendation-engine | Determines best architecture with confidence score | Step 3 | | rationale-generator | Produces context-specific pros/cons and justification | Step 4 |

Workflows

Primary: Evaluate Architecture

Path: workflows/evaluate-architecture.md

Full evaluation workflow:

Collect Inputs → Gather project info, scale, constraints
Analyze Factors → Score against decision framework
Generate Recommendation → Determine best fit with confidence
Build Rationale → Create personalized explanation
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)

| Factor | Weight | Why This Weight | |--------|--------|-----------------| | Team Size | 25% | Solo = always relevant; this is the dominant factor | | AI-Friendliness | 20% | AI agents are your "team"; architecture affects their effectiveness | | Deployment Simplicity | 15% | No DevOps team; you manage everything | | Debugging Ease | 15% | No SRE team; you troubleshoot alone | | Expected Scale | 10% | Matters less than operational simplicity for solo | | Domain Complexity | 10% | Clear domains might justify separation eventually | | Future Flexibility | 5% | Nice to have but don't over-optimize |

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

| Scenario | Monolith | Microservices | Hybrid | |----------|----------|---------------|--------| | Solo + AI agents | 100 | 10 | 50 |

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

| Development Style | Monolith | Microservices | Hybrid | |-------------------|----------|---------------|--------| | AI-first | 90 | 40 | 70 | | AI-assisted | 85 | 50 | 70 | | Traditional | 70 | 60 | 65 |

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

Deployment Simplicity (15%)

Solo devs need simple deployments

| DevOps Comfort | Monolith | Microservices | Hybrid | |----------------|----------|---------------|--------| | Beginner | 100 | 20 | 50 | | Intermediate | 90 | 40 | 65 | | Advanced | 80 | 60 | 75 |

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

Debugging Ease (15%)

Stack traces beat distributed tracing for solo devs

| Domain Complexity | Monolith | Microservices | Hybrid | |-------------------|----------|---------------|--------| | Simple | 95 | 50 | 70 | | Medium | 85 | 45 | 70 | | Complex | 75 | 40 | 65 |

Expected Scale (10%)

Scale threshold for microservices is high

| Expected Users | Monolith | Microservices | Hybrid | |----------------|----------|---------------|--------| | <10K | 95 | 30 | 50 | | 10K-100K | 80 | 50 | 70 | | 100K-1M | 60 | 70 | 80 | | >1M | 40 | 85 | 75 |

Rationale: Microservices overhead only justified at significant scale.

Domain Complexity (10%)

Clear boundaries might justify extraction later

| Domains | Monolith | Microservices | Hybrid | |---------|----------|---------------|--------| | Single | 95 | 30 | 50 | | 2-3 | 80 | 50 | 75 | | 4+ | 60 | 70 | 80 |

Future Flexibility (5%)

Plan for success, but don't over-engineer

| Growth Plan | Monolith | Microservices | Hybrid | |-------------|----------|---------------|--------| | Stay solo | 90 | 30 | 60 | | Maybe hire | 70 | 50 | 80 | | Team planned | 50 | 70 | 80 |

Architecture Variants

Monolith Variants

| Variant | When to Recommend | |---------|-------------------| | simple-monolith | Simple domain, <10K users, single platform | | modular-monolith | Medium complexity, growth expected | | api-first-monolith | Multiple platforms (web + mobile) |

Hybrid Variants

| Variant | When to Recommend | |---------|-------------------| | monolith-plus-service | Specific high-load component identified | | monolith-with-integration-layer | Heavy third-party integrations | | monolith-plus-realtime | Real-time + CRUD mixed workloads |

Hard Rules (Override Scores)

These conditions override calculated scores:

| Condition | Rule | |-----------|------| | DevOps = beginner | Never recommend microservices | | Budget = bootstrap | Favor simplest deployment | | Time to MVP < 2 months | Always recommend monolith | | Solo + microservices score high | Reduce confidence, add warnings |

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:

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

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

Error Handling

Input Validation Errors

| Error | Detection | Resolution | |-------|-----------|------------| | Missing project name | Required field empty | Prompt for name | | Invalid scale | Non-numeric or out of range | Show valid options | | Contradictory inputs | Bootstrap budget + >1M users | Flag and discuss expectations | | Incomplete context | <50% questions answered | Use defaults, reduce confidence |

Analysis Errors

| Error | Detection | Resolution | |-------|-----------|------------| | Scores too close | Top 2 within 5 points | Present both options, explain trade-offs | | No clear winner | All scores within 15 points | Gather more context or recommend safest (monolith) | | Hard rule conflict | Calculated score vs hard rule mismatch | Hard rule wins, explain override |

Output Errors

| Error | Detection | Resolution | |-------|-----------|------------| | Confidence too low | < 0.5 | Add uncertainty disclaimer, suggest revisiting inputs | | Missing rationale | Sub-agent returned incomplete | Generate fallback rationale from factors |

Technology Stack Suggestions

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

Monolith Stacks

| Stack | Best For | AI-Friendly Features | |-------|----------|---------------------| | Next.js + Prisma | Web apps, full-stack | Single repo, great TypeScript support | | Django + HTMX | Content-heavy, rapid prototyping | Excellent ORM, admin panel | | Rails | CRUD-heavy apps | Convention over configuration | | Laravel | PHP ecosystem | Eloquent ORM, built-in auth | | Go + Templ | Performance-critical | Single binary deployment |

Hybrid Stacks

| Component | Monolith | Extracted Service | |-----------|----------|-------------------| | Core app | Next.js, Django, Rails | - | | Real-time | - | Elixir/Phoenix, Go, Rust | | Heavy processing | - | Python worker, Go service | | Search | - | Elasticsearch, Typesense |

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

| Setting | Default | Override | |---------|---------|----------| | detailed_output | true | --brief | | include_alternatives | true | --no-alternatives | | factor_weights | solo-calibrated | --weights=traditional |

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