Architecture Patterns

--- name: architecture-patterns description: Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use this skill when designing clean architecture for a new microservice, when refactoring a monolith to use bounded contexts, when implementing hexagonal or onion architecture patterns, or when debugging dependency cycles between application layers. --- # Architecture Patterns Master proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design to build maintainable, testable, and scalable systems. Given: a service boundary or module to architect. Produces: layered structure with clear dependency rules, interface definitions, and test boundaries. ## When to Use This Skill - Designing new backend services or microservices from scratch - Refactoring monolithic applications where business logic is entangled with ORM models or HTTP concerns - Establishing bounded contexts before splitting a system into services - Debugging dependency cycles where infrastructure code bleeds into the domain layer - Creating testable codebases where use-case tests do not require a running database - Implementing domain-driven design tactical patterns (aggregates, value objects, domain events) ## Core Concepts ### 1. Clean Architecture (Uncle Bob) Layers (dependency flows inward): - Entities: Core business models, no framework imports - Use Cases: Application business rules, orchestrate entities - Interface Adapters: Controllers, presenters, gateways : translate between use cases and external formats - Frameworks & Drivers: UI, database, external services : all at the outermost ring Key Principles: - Dependencies point inward only; inner layers know nothing about outer layers - Business logic is independent of frameworks, databases, and delivery mechanisms - Every layer boundary is crossed via an abstract interface - Testable without UI, database, or external services ### 2. Hexagonal Architecture (Ports and Adapters) Components: - Domain Core: Business logic lives here, framework-free - Ports: Abstract interfaces that define how the core interacts with the outside world (driving and driven) - Adapters: Concrete implementations of ports (PostgreSQL adapter, Stripe adapter, REST adapter) Benefits: - Swap implementations without touching the core (e.g., replace PostgreSQL with DynamoDB) - Use in-memory adapters in tests : no Docker required - Technology decisions deferred to the edges ### 3. Domain-Driven Design (DDD) Strategic Patterns: - Bounded Contexts: Isolate a coherent model for one subdomain; avoid sharing a single model across the whole system - Context Mapping: Define how contexts relate (Anti-Corruption Layer, Shared Kernel, Open Host Service) - Ubiquitous Language: Every term in code matches the term used by domain experts Tactical Patterns: - Entities: Objects with stable identity that change over time - Value Objects: Immutable objects identified by their attributes (Email, Money, Address) - Aggregates: Consistency boundaries; only the root is accessible from outside - Repositories: Persist and reconstitute aggregates; abstract over the storage mechanism - Domain Events: Capture things that happened inside the domain; used for cross-aggregate coordination ## Detailed patterns and worked examples Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient. ## Testing : In-Memory Adapters The hallmark of correctly applied Clean Architecture is that every use case can be exercised in a plain unit test with no real database, no Docker, and no network: ```python # tests/unit/testcreateuser.py import asyncio from typing import Dict, Optional from domain.entities.user import User from domain.interfaces.userrepository import IUserRepository from usecases.createuser import CreateUserUseCase, CreateUserRequest class InMemoryUserRepository(IUserRepository): def init(self): self.store: Dict[str, User] = {} async def findbyid(self, userid: str) -> Optional[User]: return self.store.get(userid) async def findbyemail(self, email: str) -> Optional[User]: return next((u for u in self.store.values() if u.email == email), None) async def save(self, user: User) -> User: self.store[user.id] = user return user async def delete(self, userid: str) -> bool: return self.store.pop(userid, None) is not None async def testcreateusersucceeds(): repo = InMemoryUserRepository() usecase = CreateUserUseCase(userrepository=repo) response = await usecase.execute(CreateUserRequest(email="alice@example.com", name="Alice")) assert response.success assert response.user.email == "alice@example.com" assert response.user.id is not N