architecture-patterns
/architecture-patterns
Wdraża sprawdzone wzorce architektury backendu: Clean Architecture, heksagonalną i DDD, także przy rozbijaniu monolitu i cyklach zależności.
- Autor
- Vinay7766 ↗
- Repozytorium
- omni-orchestrator ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 04.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 04.11.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Wdraża sprawdzone wzorce architektury backendu: Clean Architecture, heksagonalną i DDD, także przy rozbijaniu monolitu i cyklach zależności.
Oryginalny opis (EN)
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.
Jak działa
- When to Use This Skill
- Core Concepts
- Detailed patterns and worked examples
- Testing — In-Memory Adapters
- Troubleshooting
- Advanced Patterns
- Related Skills
- Source and license
Podgląd SKILL.md
---
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/test_create_user.py
import asyncio
from typing import Dict, Optional
from domain.entities.user import User
from domain.interfaces.user_repository import IUserRepository
from use_cases.create_user import CreateUserUseCase, CreateUserRequest
class InMemoryUserRepository(IUserRepository):
def __init__(self):
self._store: Dict[str, User] = {}
async def find_by_id(self, user_id: str) -> Optional[User]:
return self._store.get(user_id)
async def find_by_email(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, user_id: str) -> bool:
return self._store.pop(user_id, None) is not None
async def test_create_user_succeeds():
repo = InMemoryUserRepository()
use_case = CreateUserUseCase(user_repository=repo)
response = await use_case.execute(CreateUserRequest(email="alice@example.com", name="Alice"))
assert response.success
assert response.user.email == "alice@example.com"
assert response.user.id is not None
async def test_duplicate_email_rejected():
repo = InMemoryUserRepository()
use_case = CreateUserUseCase(user_repository=repo)
await use_case.execute(CreateUserRequest(email="alice@example.com", name="Alice"))
response = await use_case.execute(CreateUserRequest(email="alice@example.com", name="Alice2"))
assert not response.success
assert "already exists" in response.error
```
## Troubleshooting
### Use case tests require a running database
Business logic has leaked into the infrastructure layer. Move all database calls behind an `IRepository` interface and inject an in-memory implementation in tests (see Testing section above). The use case constructor must accept the abstract port, not the concrete class.
### Circular imports between layers
A common symptom is `ImportError: cannot import name X` between `use_cases` and `adapters`. This happens when a use case imports a concrete adapter class instead of the abstract port. Enforce the rule: `use_cases/` imports only from `domain/` (entities and interfaces). It must never import from `adapters/` or `infrastructure/`.
### Framework decorators appearing in domain entities
If SQLAlchemy `Column()` or Pydantic `Field()` annotations appear on domain entities, the entity is no longer pure. Create a separate ORM model in `adapters/repositories/` and map to/from the domain entity in the repository's `_to_entity()` method.
### All logic ending up in controllers
When the controller grows beyond HTTP parsing and response formatting, extract the logic into a use case class. A controller method should do three things only: parse the request, call a use case, map the response.
### Value objects raising errors too late
Validate invariants in `__post_init__` (Python) or the constructor so an invalid `Email` or `Money` cannot be constructed at all. This surfaces bad data at the boundary, not deep inside business logic.
### Context bleed across bounded contexts
If the `Order` context is importing `User` entities from the `Identity` context, introduce an Anti-Corruption Layer. The `Order` context should hold its own lightweight `CustomerId` value object and only call the `Identity` context through an explicit interface.
## Advanced Patterns
For detailed DDD bounded context mapping, full multi-service project trees, Anti-Corruption Layer implementations, and Onion Architecture comparisons, see:
- [`references/advanced-patterns.md`](references/advanced-patterns.md)
## Related Skills
- `microservices-patterns` — Apply these architecture patterns when decomposing a monolith into services
- `cqrs-implementation` — Use Clean Architecture as the structural foundation for CQRS command/query separation
- `saga-orchestration` — Sagas require well-defined aggregate boundaries, which DDD tactical patterns provide
- `event-store-design` — Domain events produced by aggregates feed directly into an event store
---
## Source and license
Bundled from [wshobson/agents](https://github.com/wshobson/agents/blob/be57c0b2e3c05c528ca6132b87410b385718775f/plugins/backend-development/skills/architecture-patterns/SKILL.md) at commit `be57c0b`. The text above is unmodified; only this section was added. License: MIT (full text in `skills/THIRD_PARTY_LICENSES.md`). Not bundled: the optional `references/details.md` and `references/advanced-patterns.md` deep dives.
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · Vinay7766/omni-orchestrator | 100 | Apache-2.0 |
| mangowhoiscloud/geode | 100 | Apache-2.0 |
| wshobson/agents | 100 | MIT |
| sebastiendegodez/skraft-plugin | 100 | GPL-3.0 |
| secondsky/claude-skills | 100 | MIT |
| hermeticormus/claude-code-game-development | 100 | MIT |
| incubyte/ai-plugins | 100 | MIT |
| rshankras/claude-code-apple-skills | 100 | MIT |
| sequenzia/agent-alchemy | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 405d8005f866 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100clean-ddd-hexagonal
Projektuje lub przegląda granice domeny i zależności backendu według DDD, Clean Architecture i portów z adapterami: modelowanie agregatów, konteksty ograniczone i izolacja przypadków użycia. - 100hexagonal
Opisuje architekturę heksagonalną (porty i adaptery), Onion Architecture i ich związek z Clean Architecture, dla logiki domenowej niezależnej od technologii i dobrze testowalnej. - 100clean-architecture
Pomaga stosować Clean Architecture, zasady SOLID i wstrzykiwanie zależności oraz dzielić kod na testowalne warstwy, także w stylu heksagonalnym i DDD. - 100clean-architecture
Stosuje architekturę czystą i heksagonalną z wzorcami taktycznymi DDD: warstwy, encje, agregaty i repozytoria, do projektowania lub oceny struktury aplikacji. - 100clean-architecture
Dostarcza wzorce Clean Architecture, DDD i architektury heksagonalnej dla aplikacji NestJS i TypeScript, od warstwy domeny po porty i adaptery. - 100clean-architecture
Wspiera projektowanie architektury Clean Architecture z warstwami Onion i Hexagonal, odwróceniem zależności, interaktorami przypadków użycia i interfejsami repozytoriów.