System Architecture Skill
Bonded to: architecture-patterns-agent
Quick Start
bash
# Invoke architecture skill "Help me decompose this monolith into microservices" "Which design pattern should I use for notifications?" "Design an event-driven architecture for order processing"
Instructions
- •Analyze Requirements: Understand system needs and constraints
- •Apply SOLID: Use SOLID principles for clean design
- •Select Patterns: Choose appropriate design patterns
- •Design Architecture: Select monolithic or distributed approach
- •Validate Design: Review for scalability and maintainability
Architecture Selection Matrix
| Style | Best For | Team Size | Complexity | Scale |
|---|---|---|---|---|
| Monolith | MVPs, small teams | 1-10 | Low | Vertical |
| Modular Monolith | Growing apps | 5-20 | Medium | Vertical |
| Microservices | Large teams | 20+ | High | Horizontal |
| Serverless | Variable load | 1-15 | Medium | Auto |
| Event-Driven | Real-time, async | 10+ | High | Horizontal |
Decision Tree
code
Team size & complexity?
│
├─→ Small team (1-5) → Monolith
│
├─→ Growing team (5-20)
│ ├─→ Clear domain boundaries → Modular Monolith
│ └─→ Variable load → Serverless
│
└─→ Large team (20+)
├─→ Real-time/async heavy → Event-Driven
└─→ Independent scaling needed → Microservices
SOLID Principles
| Principle | Description | Violation Sign |
|---|---|---|
| Single Responsibility | One reason to change | Class does too many things |
| Open/Closed | Open for extension, closed for mod | Editing existing code for new features |
| Liskov Substitution | Subtypes substitutable | Subclass changes behavior unexpectedly |
| Interface Segregation | Small, specific interfaces | Clients implement unused methods |
| Dependency Inversion | Depend on abstractions | High-level depends on low-level |
Design Patterns Quick Reference
Creational
| Pattern | Use Case |
|---|---|
| Singleton | Global config, connection pools |
| Factory | Object creation with logic |
| Builder | Complex object construction |
Structural
| Pattern | Use Case |
|---|---|
| Adapter | Interface compatibility |
| Decorator | Dynamic behavior extension |
| Facade | Simplified interface |
| Proxy | Access control, caching |
Behavioral
| Pattern | Use Case |
|---|---|
| Observer | Event notifications |
| Strategy | Algorithm selection |
| Command | Action encapsulation |
| State | State machines |
Examples
Example 1: Microservices Decomposition
code
E-commerce Monolith → Microservices Services: ├── user-service (auth, profiles) ├── product-service (catalog, inventory) ├── order-service (orders, checkout) ├── payment-service (transactions) ├── notification-service (email, push) └── api-gateway (routing, auth) Communication: ├── Sync: REST/gRPC for queries └── Async: Event bus for commands/events
Example 2: Observer Pattern
python
from abc import ABC, abstractmethod
from typing import List
class Observer(ABC):
@abstractmethod
def update(self, event: dict) -> None:
pass
class NotificationService:
def __init__(self):
self._observers: List[Observer] = []
def subscribe(self, observer: Observer) -> None:
self._observers.append(observer)
def notify(self, event: dict) -> None:
for observer in self._observers:
observer.update(event)
class EmailHandler(Observer):
def update(self, event: dict) -> None:
send_email(event["user_id"], event["message"])
class PushHandler(Observer):
def update(self, event: dict) -> None:
send_push(event["user_id"], event["message"])
Example 3: Event-Driven Order Processing
python
# Saga pattern for order processing
class OrderSaga:
async def process_order(self, order_id: str):
try:
# Step 1: Reserve inventory
await self.inventory_service.reserve(order_id)
# Step 2: Process payment
await self.payment_service.charge(order_id)
# Step 3: Confirm order
await self.order_service.confirm(order_id)
except PaymentError:
# Compensating transaction
await self.inventory_service.release(order_id)
await self.order_service.cancel(order_id)
raise
Troubleshooting
Anti-Pattern Detection
| Anti-Pattern | Sign | Solution |
|---|---|---|
| Distributed Monolith | Services too coupled | Define bounded contexts |
| God Class | One class does everything | Extract by responsibility |
| Circular Dependencies | A→B→C→A | Introduce interfaces |
| Shared Database | Multiple services, one DB | Database per service |
Debug Checklist
- •Review dependency graph: Check for cycles
- •Analyze coupling: Services should be loosely coupled
- •Check cohesion: Related functionality together
- •Validate boundaries: Clear service boundaries
- •Test in isolation: Services deployable independently
Test Template
python
# tests/test_architecture.py
import pytest
class TestServiceBoundaries:
def test_services_are_independent(self):
# Each service should work independently
user_service = UserService()
order_service = OrderService()
# Services communicate via events/APIs, not direct calls
assert not hasattr(order_service, 'user_repository')
def test_no_circular_dependencies(self):
from app.services import dependency_graph
cycles = dependency_graph.find_cycles()
assert len(cycles) == 0
References
See references/ directory for:
- •
ARCHITECTURE_GUIDE.md- Detailed patterns - •
design-patterns.yaml- Pattern catalog