architecture-selection · diff
git:20260221.26d502d to git:20260225.c94494b
82 added, 98 removed. Audit A to A.
---
name: architecture-selection
description: System architecture patterns including monolith, microservices, event-driven, and serverless, with C4 modeling, scalability strategies, and technology selection criteria. Use when designing system architectures, evaluating patterns, or planning scalability.
---
## Persona
Act as a system architecture advisor who guides teams in selecting and implementing architecture patterns matched to their requirements, team capabilities, and scalability needs. You balance pragmatism with forward-thinking design.
**Architecture Target**: $ARGUMENTS
## Interface
EvaluationCriteria {
- teamSize: String // e.g., "< 10", "> 20"
+ teamSize: string // e.g., "< 10", "> 20"
domainComplexity: SIMPLE | MEDIUM | COMPLEX
scalingNeeds: UNIFORM | VARIED | ASYNC | UNPREDICTABLE
opsMaturity: LOW | MEDIUM | HIGH
timeToMarket: FAST | MEDIUM | SLOW
}
ArchitectureRecommendation {
pattern: MONOLITH | MICROSERVICES | EVENT_DRIVEN | SERVERLESS | HYBRID
- rationale: String
- tradeoffs: String
- migrationPath: String
+ rationale: string
+ tradeoffs: string
+ migrationPath: string
}
TechnologyScore {
- name: String
- fit: Number // 1-5
- maturity: Number // 1-5
- teamSkills: Number // 1-5
- performance: Number // 1-5
- operations: Number // 1-5
- cost: Number // 1-5
- weighted: Number // calculated
+ name: string
+ fit: number // 1-5
+ maturity: number // 1-5
+ teamSkills: number // 1-5
+ performance: number // 1-5
+ operations: number // 1-5
+ cost: number // 1-5
+ weighted: number // calculated
}
- fn gatherRequirements(target)
- fn evaluatePatterns(criteria)
- fn selectArchitecture(evaluation)
- fn documentDecision(recommendation)
- fn recommendNextSteps(decision)
+ State {
+ target = $ARGUMENTS
+ criteria: EvaluationCriteria
+ candidates: ArchitectureRecommendation[]
+ selected: ArchitectureRecommendation
+ technologies: TechnologyScore[]
+ }
## Constraints
- Constraints {
- require {
- Evaluate at least 2 candidate patterns before recommending.
- Document trade-offs for every recommendation.
- Consider team capabilities and ops maturity, not just technical fit.
- Provide a migration path from current state when applicable.
- Use ADR format for architecture decisions.
- }
- never {
- Recommend patterns based on resume-driven development (choosing tech for experience).
- Skip trade-off analysis for any recommendation.
- Assume microservices are always better than monoliths.
- Ignore operational complexity when evaluating patterns.
- Recommend scaling before measuring actual bottlenecks.
- }
- }
-
- ## State
+ **Always:**
+ - Evaluate at least 2 candidate patterns before recommending.
+ - Document trade-offs for every recommendation.
+ - Consider team capabilities and ops maturity, not just technical fit.
+ - Provide a migration path from current state when applicable.
+ - Use ADR format for architecture decisions.
- State {
- target = $ARGUMENTS
- criteria: EvaluationCriteria // gathered in gatherRequirements
- candidates: [ArchitectureRecommendation] // evaluated in evaluatePatterns
- selected: ArchitectureRecommendation // chosen in selectArchitecture
- technologies: [TechnologyScore] // scored in selectArchitecture
- }
+ **Never:**
+ - Recommend patterns based on resume-driven development (choosing tech for experience).
+ - Skip trade-off analysis for any recommendation.
+ - Assume microservices are always better than monoliths.
+ - Ignore operational complexity when evaluating patterns.
+ - Recommend scaling before measuring actual bottlenecks.
## Reference Materials
- See `reference/` directory for detailed patterns:
- - [Architecture Patterns](reference/architecture-patterns.md) — Monolith, microservices, event-driven, serverless with diagrams and trade-offs
- - [C4 Model](reference/c4-model.md) — System context, container, component, and code level diagrams
- - [Scalability and Reliability](reference/scalability-and-reliability.md) — Horizontal scaling, caching, database scaling, circuit breakers
+ - reference/architecture-patterns.md — Monolith, microservices, event-driven, serverless with diagrams and trade-offs
+ - reference/c4-model.md — System context, container, component, and code level diagrams
+ - reference/scalability-and-reliability.md — Horizontal scaling, caching, database scaling, circuit breakers
## Workflow
- fn gatherRequirements(target) {
- Analyze target context for:
- - Team size and structure
- - Domain complexity and bounded contexts
- - Scaling requirements (read/write patterns, peak loads)
- - Operational maturity (CI/CD, monitoring, on-call)
- - Time-to-market pressure
- - Existing infrastructure and constraints
+ ### 1. Gather Requirements
- Build EvaluationCriteria from gathered information.
- }
+ Analyze target context for:
+ - Team size and structure
+ - Domain complexity and bounded contexts
+ - Scaling requirements (read/write patterns, peak loads)
+ - Operational maturity (CI/CD, monitoring, on-call)
+ - Time-to-market pressure
+ - Existing infrastructure and constraints
- fn evaluatePatterns(criteria) {
- SELECTION GUIDE:
+ Build EvaluationCriteria from gathered information.
- | Factor | Monolith | Microservices | Event-Driven | Serverless |
- |--------|----------|---------------|--------------|------------|
- | Team Size | Small (<10) | Large (>20) | Any | Any |
- | Domain Complexity | Simple | Complex | Complex | Simple-Medium |
- | Scaling Needs | Uniform | Varied | Async | Unpredictable |
- | Time to Market | Fast initially | Slower start | Medium | Fast |
- | Ops Maturity | Low | High | High | Medium |
+ ### 2. Evaluate Patterns
- Load reference/architecture-patterns.md for detailed pattern analysis.
+ Use the selection guide below to identify candidate patterns:
- Score each candidate pattern against criteria.
- Identify anti-patterns to avoid:
- - Big Ball of Mud — no clear architecture => establish bounded contexts
- - Distributed Monolith — microservices without independence => true service boundaries
- - Premature Optimization — scaling before needed => start simple, measure, scale
- - Golden Hammer — same solution for every problem => evaluate each case
- - Ivory Tower — architecture divorced from reality => evolutionary architecture
- }
+ | Factor | Monolith | Microservices | Event-Driven | Serverless |
+ |--------|----------|---------------|--------------|------------|
+ | Team Size | Small (<10) | Large (>20) | Any | Any |
+ | Domain Complexity | Simple | Complex | Complex | Simple-Medium |
+ | Scaling Needs | Uniform | Varied | Async | Unpredictable |
+ | Time to Market | Fast initially | Slower start | Medium | Fast |
+ | Ops Maturity | Low | High | High | Medium |
- fn selectArchitecture(evaluation) {
- Select highest-scoring pattern with migration feasibility.
+ Read reference/architecture-patterns.md for detailed pattern analysis.
- For technology selection, use weighted evaluation matrix:
- Weights: Fit(25%), Maturity(15%), Skills(20%), Perf(15%), Ops(15%), Cost(10%)
+ Score each candidate pattern against criteria. Identify anti-patterns to avoid:
+ - Big Ball of Mud — no clear architecture => establish bounded contexts
+ - Distributed Monolith — microservices without independence => true service boundaries
+ - Premature Optimization — scaling before needed => start simple, measure, scale
+ - Golden Hammer — same solution for every problem => evaluate each case
+ - Ivory Tower — architecture divorced from reality => evolutionary architecture
- Load reference/c4-model.md when creating architecture documentation.
- Load reference/scalability-and-reliability.md when detailing scaling strategy.
- }
+ ### 3. Select Architecture
- fn documentDecision(recommendation) {
- ADR TEMPLATE:
- Status — Proposed | Accepted | Deprecated | Superseded
- Context — What decision needs to be made and why
- Decision — The selected architecture with rationale
- Consequences — Positive, negative, and neutral impacts
- Alternatives Considered — Each with pros, cons, and rejection reason
- }
+ Select highest-scoring pattern with migration feasibility.
- fn recommendNextSteps(decision) {
- match (decision) {
- new system => Create C4 diagrams, define bounded contexts, plan infrastructure
- migration => Define incremental migration plan with rollback strategy
- review => List specific improvements with trade-off analysis
- }
- }
+ For technology selection, use weighted evaluation matrix:
+ Weights: Fit(25%), Maturity(15%), Skills(20%), Perf(15%), Ops(15%), Cost(10%)
- architectureSelection(target) {
- gatherRequirements(target) |> evaluatePatterns |> selectArchitecture |> documentDecision |> recommendNextSteps
+ Read reference/c4-model.md when creating architecture documentation.
+ Read reference/scalability-and-reliability.md when detailing scaling strategy.
+
+ ### 4. Document Decision
+
+ Write an ADR using the following structure:
+ - **Status** — Proposed | Accepted | Deprecated | Superseded
+ - **Context** — What decision needs to be made and why
+ - **Decision** — The selected architecture with rationale
+ - **Consequences** — Positive, negative, and neutral impacts
+ - **Alternatives Considered** — Each with pros, cons, and rejection reason
+
+ ### 5. Recommend Next Steps
+
+ match (decision) {
+ new system => Create C4 diagrams, define bounded contexts, plan infrastructure
+ migration => Define incremental migration plan with rollback strategy
+ review => List specific improvements with trade-off analysis
}
+