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.
/plugin marketplace add rsmdt/the-startup/plugin install team@the-startupThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Systematic guidance for selecting and implementing architecture patterns that match requirements, team capabilities, and scalability needs.
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:
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 |
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:
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 |
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:
Trade-offs:
| Pros | Cons |
|---|---|
| Temporal decoupling | Eventual consistency |
| Natural audit log | Complex debugging |
| Scalability | Message ordering challenges |
| Extensibility | Infrastructure requirements |
| Resilience | Learning curve |
Functions executed on-demand without managing servers.
┌────────────────────────────────────────────────────────────┐
│ Client │
└────────────────────────────┬───────────────────────────────┘
│
┌────────────────────────────┴───────────────────────────────┐
│ API Gateway │
└────────────────────────────┬───────────────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Function │ │ Function │ │ Function │
│ GetUser │ │CreateOrder│ │ SendEmail│
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Database │ │ Queue │ │ Email │
│ │ │ │ │ Service │
└──────────┘ └──────────┘ └──────────┘
When to Use:
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 |
| 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 |
Hierarchical way to document architecture at multiple levels of detail.
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] │ │
│ └───────────────┘ └───────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
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] │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
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 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
Shows implementation details (class diagrams, sequence diagrams).
Use standard UML when needed at this level.
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
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
| 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 |
| 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 ────── │ │
└─────────┘ └─────────┘
| 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? |
| 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%)
# 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-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 |
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.