home / skills / rsmdt / the-startup / architecture-selection
This skill helps you choose and document suitable system architecture patterns monolith microservices event-driven serverless for scalability.
npx playbooks add skill rsmdt/the-startup --skill architecture-selectionReview the files below or copy the command above to add this skill to your agents.
---
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.
---
# Architecture Pattern Selection
Systematic guidance for selecting and implementing architecture patterns that match requirements, team capabilities, and scalability needs.
## When to Activate
- Designing new system architectures
- Evaluating monolith vs microservices vs serverless
- Planning scalability strategies
- Selecting technology stacks
- Creating architecture documentation
- Reviewing architecture decisions
## Architecture Patterns
### Monolithic Architecture
A single deployable unit containing all functionality.
```
┌─────────────────────────────────────────────────────────────┐
│ Monolithic Application │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Web UI │ │ API Layer │ │ Admin UI │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ │
│ ┌───────────────────────┴───────────────────────────┐ │
│ │ Business Logic Layer │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Orders │ │ Users │ │ Products │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └───────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌───────────────────────┴───────────────────────────┐ │
│ │ Data Access Layer │ │
│ └───────────────────────┬───────────────────────────┘ │
│ │ │
└──────────────────────────┼──────────────────────────────────┘
│
┌──────┴──────┐
│ Database │
└─────────────┘
```
**When to Use:**
- Small team (< 10 developers)
- Simple domain
- Rapid iteration needed
- Limited infrastructure expertise
**Trade-offs:**
| Pros | Cons |
|------|------|
| Simple deployment | Limited scalability |
| Easy debugging | Large codebase to manage |
| Single codebase | Technology lock-in |
| Fast development initially | Team coupling |
| Transactional consistency | Full redeploy for changes |
### Microservices Architecture
Independently deployable services organized around business capabilities.
```
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Web UI │ │Mobile │ │ Admin │ │External│
└───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘
│ │ │ │
└────────────┴────────────┴────────────┘
│
┌────────┴────────┐
│ API Gateway │
└────────┬────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌───┴───┐ ┌────┴───┐ ┌───┴───┐
│ Order │ │ User │ │Product│
│Service│ │Service │ │Service│
├───────┤ ├────────┤ ├───────┤
│ DB │ │ DB │ │ DB │
└───────┘ └────────┘ └───────┘
│ │ │
└──────────────────┴──────────────────┘
│
┌────────┴────────┐
│ Message Bus │
└─────────────────┘
```
**When to Use:**
- Large team (> 20 developers)
- Complex, evolving domain
- Independent scaling needed
- Different tech stacks for different services
- High availability requirements
**Trade-offs:**
| Pros | Cons |
|------|------|
| Independent deployment | Operational complexity |
| Technology flexibility | Network latency |
| Team autonomy | Distributed debugging |
| Targeted scaling | Data consistency challenges |
| Fault isolation | More infrastructure |
### Event-Driven Architecture
Services communicate through events rather than direct calls.
```
┌─────────────────────────────────────────────────────────────┐
│ Event Bus / Broker │
├─────────────────────────────────────────────────────────────┤
│ │
│ OrderPlaced UserCreated PaymentReceived │
│ │
└──────┬──────────────┬──────────────┬───────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Order │ │ User │ │ Payment │
│ Service │ │ Service │ │ Service │
│ │ │ │ │ │
│ Publishes: │ │ Publishes: │ │ Publishes: │
│ OrderPlaced │ │ UserCreated │ │ PaymentRcvd │
│ │ │ │ │ │
│ Subscribes: │ │ Subscribes: │ │ Subscribes: │
│ PaymentRcvd │ │ OrderPlaced │ │ OrderPlaced │
└─────────────┘ └─────────────┘ └─────────────┘
```
**When to Use:**
- Loose coupling required
- Asynchronous processing acceptable
- Complex workflows spanning multiple services
- Audit trail needed
- Event sourcing scenarios
**Trade-offs:**
| Pros | Cons |
|------|------|
| Temporal decoupling | Eventual consistency |
| Natural audit log | Complex debugging |
| Scalability | Message ordering challenges |
| Extensibility | Infrastructure requirements |
| Resilience | Learning curve |
### Serverless Architecture
Functions executed on-demand without managing servers.
```
┌────────────────────────────────────────────────────────────┐
│ Client │
└────────────────────────────┬───────────────────────────────┘
│
┌────────────────────────────┴───────────────────────────────┐
│ API Gateway │
└────────────────────────────┬───────────────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Function │ │ Function │ │ Function │
│ GetUser │ │CreateOrder│ │ SendEmail│
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Database │ │ Queue │ │ Email │
│ │ │ │ │ Service │
└──────────┘ └──────────┘ └──────────┘
```
**When to Use:**
- Variable/unpredictable workloads
- Event-triggered processing
- Cost optimization for low traffic
- Rapid development needed
- Short-running operations
**Trade-offs:**
| Pros | Cons |
|------|------|
| No server management | Cold start latency |
| Pay-per-use | Execution time limits |
| Auto-scaling | Vendor lock-in |
| Rapid deployment | Complex local development |
| Reduced ops burden | Stateless constraints |
### Pattern Selection Guide
| 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 |
## C4 Model
Hierarchical way to document architecture at multiple levels of detail.
### Level 1: System Context
Shows system in its environment with external actors and systems.
```
┌──────────────────────────────────────────────────────────────┐
│ System Context Diagram │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Customer │ │ Admin │ │
│ │ [User] │ │ [User] │ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ │ Places orders │ Manages │
│ │ │ products │
│ ▼ ▼ │
│ ┌────────────────────────────────────────────────┐ │
│ │ E-Commerce System │ │
│ │ [Software System] │ │
│ └───────────┬─────────────────┬──────────────────┘ │
│ │ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ │
│ │ Payment │ │ Email │ │
│ │ Gateway │ │ Provider │ │
│ │ [External] │ │ [External] │ │
│ └───────────────┘ └───────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
```
### Level 2: Container
Shows the high-level technology choices and how containers communicate.
```
┌──────────────────────────────────────────────────────────────┐
│ Container Diagram │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Web App │ │ Mobile App │ │
│ │ [React SPA] │ │ [React Native] │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ │ HTTPS │ │
│ └───────────┬───────────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ API Gateway │ │
│ │ [Kong] │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Order │ │ User │ │ Product │ │
│ │ Service │ │ Service │ │ Service │ │
│ │ [Node] │ │ [Node] │ │ [Go] │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Orders │ │ Users │ │Products │ │
│ │ DB │ │ DB │ │ DB │ │
│ │[Postgres│ │[Postgres│ │ [Mongo] │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
```
### Level 3: Component
Shows internal structure of a container.
```
┌──────────────────────────────────────────────────────────────┐
│ Component Diagram: Order Service │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ API Layer │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ OrdersCtrl │ │ HealthCtrl │ │ MetricsCtrl │ │ │
│ │ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────┼─────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────┼─────────────────────────────────────────────┐ │
│ │ ▼ Domain Layer │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │OrderService │ │ OrderCalc │ │ Validators │ │ │
│ │ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────┼─────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────┼─────────────────────────────────────────────┐ │
│ │ ▼ Infrastructure Layer │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ OrderRepo │ │PaymentClient│ │ EventPub │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
```
### Level 4: Code
Shows implementation details (class diagrams, sequence diagrams).
*Use standard UML when needed at this level.*
## Scalability Patterns
### Horizontal Scaling
Add more instances of the same component.
```
Load Balancer
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│Instance │ │Instance │ │Instance │
│ 1 │ │ 2 │ │ 3 │
└─────────┘ └─────────┘ └─────────┘
Requirements:
- Stateless services
- Shared session storage
- Database can handle connections
```
### Caching
Reduce load on slow resources.
```
┌─────────────────────────────────────────────────────┐
│ Caching Layers │
├─────────────────────────────────────────────────────┤
│ │
│ Browser Cache → CDN → App Cache → Database Cache │
│ │
│ Examples: │
│ - Browser: Static assets, API responses │
│ - CDN: Static content, cached API responses │
│ - App: Redis/Memcached for sessions, computed data│
│ - Database: Query cache, connection pooling │
│ │
└─────────────────────────────────────────────────────┘
Cache Invalidation Strategies:
- TTL (Time to Live): Simplest, eventual consistency
- Write-through: Update cache on write
- Write-behind: Async update for performance
- Cache-aside: App manages cache explicitly
```
### Database Scaling
| Strategy | Use Case | Trade-off |
|----------|----------|-----------|
| **Read Replicas** | Read-heavy workloads | Replication lag |
| **Sharding** | Large datasets | Query complexity |
| **Partitioning** | Time-series data | Partition management |
| **CQRS** | Different read/write patterns | System complexity |
### Reliability Patterns
| Pattern | Purpose | Implementation |
|---------|---------|----------------|
| **Circuit Breaker** | Prevent cascade failures | Fail fast after threshold |
| **Bulkhead** | Isolate failures | Separate thread pools |
| **Retry** | Handle transient failures | Exponential backoff |
| **Timeout** | Bound wait times | Don't wait forever |
| **Rate Limiting** | Prevent overload | Throttle requests |
```
Circuit Breaker States:
┌────────┐
│ CLOSED │ ──── Failure Threshold ──► ┌────────┐
│(normal)│ │ OPEN │
└────────┘ │(failing│
▲ └────┬───┘
│ │
Success Timeout
Threshold │
│ ▼
┌────┴────┐ ┌─────────┐
│HALF-OPEN│ ◄─── Test Request ────── │ │
└─────────┘ └─────────┘
```
## Technology Selection
### Selection Criteria
| Criterion | Questions |
|-----------|-----------|
| **Fit** | Does it solve the actual problem? |
| **Maturity** | Production-proven? Community size? |
| **Team Skills** | Can the team use it effectively? |
| **Performance** | Meets requirements? Benchmarks? |
| **Operations** | How hard to deploy, monitor, debug? |
| **Cost** | License, infrastructure, learning curve? |
| **Lock-in** | Exit strategy? Standards compliance? |
| **Security** | Track record? Compliance certifications? |
### Evaluation Matrix
```
| Technology | Fit | Maturity | Skills | Perf | Ops | Cost | Score |
|------------|-----|----------|--------|------|-----|------|-------|
| Option A | 4 | 5 | 3 | 4 | 4 | 3 | 3.8 |
| Option B | 5 | 3 | 4 | 5 | 2 | 4 | 3.8 |
| Option C | 3 | 4 | 5 | 3 | 5 | 5 | 4.2 |
Weights: Fit(25%), Maturity(15%), Skills(20%), Perf(15%), Ops(15%), Cost(10%)
```
## Architecture Decision Records (ADRs)
### ADR Template
```markdown
# ADR-[NUMBER]: [TITLE]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Context
[What is the issue we're facing? What decision needs to be made?]
## Decision
[What is the change we're proposing/making?]
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Trade-off 1]
- [Trade-off 2]
### Neutral
- [Observation]
## Alternatives Considered
### Alternative 1: [Name]
- Pros: [...]
- Cons: [...]
- Why rejected: [...]
```
## Anti-Patterns
| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| **Big Ball of Mud** | No clear architecture | Establish bounded contexts |
| **Distributed Monolith** | Microservices without independence | True service boundaries |
| **Resume-Driven** | Choosing tech for experience | Match tech to requirements |
| **Premature Optimization** | Scaling before needed | Start simple, measure, scale |
| **Ivory Tower** | Architecture divorced from reality | Evolutionary architecture |
| **Golden Hammer** | Same solution for every problem | Evaluate each case |
## References
- [Pattern Examples](examples/architecture-patterns.md) - Detailed implementations
- [ADR Repository](examples/adrs/) - Example decision records
This skill provides practical guidance for selecting system architecture patterns (monolith, microservices, event-driven, serverless) and documenting choices with the C4 model. It helps match patterns to team size, domain complexity, scaling needs, and operational maturity. The skill also recommends scalability strategies and technology selection criteria to support implementation.
The skill evaluates requirements such as team size, domain complexity, SLAs, scaling profile, and operational capability to recommend fitting patterns and trade-offs. It maps recommendations to C4 documentation levels (System Context, Container, Component, Code) and suggests concrete scalability patterns (horizontal scaling, message buses, CQRS, caching). It also provides technology selection criteria and checklist items for deployment, monitoring, and testing.
How do I decide between monolith and microservices?
Compare team size, domain complexity, required independent scaling, and ops maturity. Choose monolith for small teams and simple domains; choose microservices when teams are large, boundaries are clear, and operational capability exists.
When is event-driven architecture a poor fit?
Avoid event-driven design when synchronous consistency is mandatory, team familiarity with distributed systems is low, or debugging and ordering guarantees would create unacceptable risk.