ruslan-korneev/plugins/tech-lead/skills/architecture-patterns

Architecture Patterns

System-level architecture patterns for Python backend projects (FastAPI + SQLAlchemy 2.0).

Triggers

Use this skill when the user:

• Designs a new system or major feature
• Asks about project structure or module boundaries
• Makes data modeling decisions
• Designs API contracts
• Evaluates architectural trade-offs
• Creates or reviews Architecture Decision Records (ADR)
• Needs to modernize legacy code

Abstraction Levels

| Plugin | Level | Focus | |--------|-------|-------| | software-architect | System | Architecture, modules, ADR | | fastapi-scaffold | Module | Boilerplate generation | | clean-code | Code | SOLID, code smells |

5 Core Principles

1. Modularity & Separation of Concerns

# Good — clear module boundaries
src/
├── core/           # Infrastructure (config, db, exceptions)
├── modules/
│   ├── users/      # User domain — fully autonomous
│   ├── orders/     # Order domain — depends on users via interfaces
│   └── payments/   # Payment domain — depends on orders via interfaces
└── main.py

# Bad — tangled dependencies
src/
├── models.py       # All models in one file
├── services.py     # All services mixed
├── routes.py       # All routes together
└── utils.py        # "Utils" — the graveyard of architecture

2. Scalability (Stateless, Horizontal Scaling)

# Good — stateless service, state in external storage
class OrderService:
    def __init__(self, cache: CacheProtocol, db: AsyncSession):
        self._cache = cache  # Redis
        self._db = db        # PostgreSQL

    async def get_order(self, order_id: int) -> Order:
        # Check cache first
        cached = await self._cache.get(f"order:{order_id}")
        if cached:
            return Order.model_validate_json(cached)
        # Fallback to DB
        return await self._repository.get_by_id(order_id)

# Bad — state in memory
class OrderService:
    _orders_cache: dict[int, Order] = {}  # Lost on restart!

3. Maintainability (Testability, Clear Organization)

# Good — dependencies via constructor (easy to test)
class UserService:
    def __init__(
        self,
        repository: UserRepositoryProtocol,
        email_sender: EmailSenderProtocol,
    ):
        self._repository = repository
        self._email_sender = email_sender

# Test with mocks
async def test_create_user():
    mock_repo = Mock(spec=UserRepositoryProtocol)
    mock_email = Mock(spec=EmailSenderProtocol)
    service = UserService(mock_repo, mock_email)
    # ...

# Bad — hidden dependencies
class UserService:
    def create_user(self, data: UserCreate) -> User:
        from app.email import send_email  # Hidden import!
        from app.db import get_session    # Hidden dependency!

4. Security (Defense in Depth, Least Privilege)

# Good — validation at every layer
# Router layer
@router.post("/orders")
async def create_order(
    data: OrderCreateDTO,  # Pydantic validation
    current_user: Annotated[User, Depends(get_current_user)],  # Auth
) -> OrderReadDTO:
    # Authorization check
    if not current_user.can_create_orders:
        raise ForbiddenError("User cannot create orders")
    return await service.create(data, current_user.id)

# Service layer
class OrderService:
    async def create(self, data: OrderCreateDTO, user_id: int) -> Order:
        # Business rules validation
        if data.total > MAX_ORDER_AMOUNT:
            raise ValidationError("Order amount exceeds limit")
        # ...

# Repository layer — parameterized queries only
async def get_by_id(self, order_id: int) -> Order | None:
    stmt = select(Order).where(Order.id == order_id)  # No f-strings!
    result = await self._session.execute(stmt)
    return result.scalar_one_or_none()

5. Performance (Efficient Algorithms, Caching)

# Good — selective loading, caching
class OrderRepository:
    async def get_with_items(self, order_id: int) -> Order:
        stmt = (
            select(Order)
            .options(selectinload(Order.items))  # Eager load
            .where(Order.id == order_id)
        )
        return (await self._session.execute(stmt)).scalar_one()

    async def get_list(
        self,
        offset: int = 0,
        limit: int = 20,
    ) -> Sequence[Order]:
        stmt = select(Order).offset(offset).limit(limit)  # Pagination
        return (await self._session.execute(stmt)).scalars().all()

# Bad — N+1 queries, no pagination
async def get_all_with_items(self) -> list[Order]:
    orders = await self._session.execute(select(Order))
    for order in orders:
        _ = order.items  # N+1 query for each order!
    return orders.scalars().all()

Architectural Patterns

More details: ${CLAUDE_PLUGIN_ROOT}/skills/architecture-patterns/references/layered-architecture.md

Layered Architecture

┌─────────────────────────────────────────┐
│           Presentation Layer            │
│        (Routers, DTOs, OpenAPI)         │
├─────────────────────────────────────────┤
│           Application Layer             │
│     (Services, Use Cases, Events)       │
├─────────────────────────────────────────┤
│             Domain Layer                │
│   (Entities, Value Objects, Rules)      │
├─────────────────────────────────────────┤
│         Infrastructure Layer            │
│   (Repositories, External Services)     │
└─────────────────────────────────────────┘

Dependency Rule: Dependencies point inward. Inner layers don't know about outer layers.

Repository Pattern

from abc import abstractmethod
from typing import Protocol, Generic, TypeVar

T = TypeVar("T")


class RepositoryProtocol(Protocol[T]):
    """Abstract repository interface."""

    @abstractmethod
    async def get_by_id(self, id: int) -> T | None: ...

    @abstractmethod
    async def save(self, entity: T) -> T: ...

    @abstractmethod
    async def delete(self, id: int) -> None: ...


class SQLAlchemyRepository(RepositoryProtocol[T]):
    """Concrete implementation for SQLAlchemy."""

    def __init__(self, session: AsyncSession, model: type[T]):
        self._session = session
        self._model = model

    async def get_by_id(self, id: int) -> T | None:
        return await self._session.get(self._model, id)

Event-Driven Architecture

from dataclasses import dataclass
from typing import Callable, Awaitable

@dataclass
class DomainEvent:
    """Base domain event."""
    pass

@dataclass
class UserCreated(DomainEvent):
    user_id: int
    email: str

class EventBus:
    def __init__(self):
        self._handlers: dict[type[DomainEvent], list[Callable]] = {}

    def subscribe(
        self,
        event_type: type[DomainEvent],
        handler: Callable[[DomainEvent], Awaitable[None]],
    ) -> None:
        self._handlers.setdefault(event_type, []).append(handler)

    async def publish(self, event: DomainEvent) -> None:
        for handler in self._handlers.get(type(event), []):
            await handler(event)

# Usage
event_bus = EventBus()
event_bus.subscribe(UserCreated, send_welcome_email)
event_bus.subscribe(UserCreated, create_default_settings)

# In service
await event_bus.publish(UserCreated(user_id=user.id, email=user.email))

CQRS (Command Query Responsibility Segregation)

# Commands — write operations
class CreateOrderCommand:
    user_id: int
    items: list[OrderItemDTO]

class CommandHandler:
    async def handle(self, command: CreateOrderCommand) -> int:
        # Complex write logic with validation
        order = Order(user_id=command.user_id)
        for item in command.items:
            order.add_item(item)
        await self._repository.save(order)
        return order.id

# Queries — read operations (can use different DB, denormalized views)
class OrderQueryService:
    async def get_order_summary(self, order_id: int) -> OrderSummaryDTO:
        # Optimized read query, possibly from read replica
        return await self._read_repository.get_summary(order_id)

Anti-Patterns

More details: ${CLAUDE_PLUGIN_ROOT}/skills/architecture-patterns/references/anti-patterns.md

| Anti-Pattern | Description | Solution | |--------------|-------------|----------| | Big Ball of Mud | No structure, everything depends on everything | Modular architecture | | Golden Hammer | Using one technology for everything | Choose right tool for the job | | Tight Coupling | Direct dependencies between modules | Interfaces, DI | | God Object | One class knows and does everything | Single Responsibility | | Circular Dependencies | A → B → C → A | Dependency Inversion |

Plugin Commands

• /architect:design <name> — interactive architecture design for new project/module
• /architect:modernize [path] — legacy analysis + phased modernization plan
• /architect:review [path] — architecture analysis (structure, dependencies, patterns)
• /architect:adr <title> — create Architecture Decision Record
• /architect:diagram <type> — generate Mermaid diagram (component, data-flow, sequence, er, deployment)
• /architect:deps [path] — dependency analysis, detect circular dependencies