System Architecture Skill

Bonded to: architecture-patterns-agent

Quick Start

# 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

1. Analyze Requirements: Understand system needs and constraints
2. Apply SOLID: Use SOLID principles for clean design
3. Select Patterns: Choose appropriate design patterns
4. Design Architecture: Select monolithic or distributed approach
5. Validate Design: Review for scalability and maintainability

Architecture Selection Matrix

Decision Tree

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

Design Patterns Quick Reference

Creational

Structural

Behavioral

Examples

Example 1: Microservices Decomposition

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

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

# 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

Debug Checklist

1. Review dependency graph: Check for cycles
2. Analyze coupling: Services should be loosely coupled
3. Check cohesion: Related functionality together
4. Validate boundaries: Clear service boundaries
5. Test in isolation: Services deployable independently

Test Template

# 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

Resources

• Martin Fowler - Patterns
• Microsoft Cloud Patterns
• DDD Reference