ddd-hexagonal-architecture skill

Overview

This skill provides practical guidance for designing and implementing hexagonal (ports and adapters) architecture with a focus on domain isolation and dependency inversion. It offers concrete patterns, folder layouts, and code-level recommendations for Python applications. Use it to structure systems that are testable, maintainable, and independent from frameworks and infrastructure.

How this skill works

The skill explains the core concepts: defining domain models and use cases inside the application core, exposing ports as interfaces, and implementing adapters for persistence, messaging, UI, and external APIs. It shows how to invert dependencies so the core depends only on abstractions and how adapters bind to those abstractions at the application boundary. The guidance includes recommended module layouts, example adapter responsibilities, and testing strategies to keep the domain isolated.

When to use it

• Starting a new backend service where long-term maintainability and testability matter
• Refactoring a monolithic codebase to improve separation of concerns and reduce coupling to frameworks
• Designing microservices where clear input/output boundaries and replaceable infrastructure are needed
• Building systems that must be easily testable with unit and integration tests
• Integrating third-party services without letting external API details leak into domain logic

Best practices

• Keep the domain layer free of framework and infrastructure imports; express behavior via pure functions, domain entities, and interfaces
• Define explicit use case/application services that orchestrate domain operations and expose ports for input and output
• Model ports as small, intention-revealing interfaces; adapters implement a single responsibility and map between external data and domain types
• Prefer constructor or dependency injection composition at the application root to wire adapters to ports, not global config or singletons
• Write unit tests for domain and use cases using fake or in-memory adapters; reserve integration tests for adapter wiring and external contracts
• Document adapter contracts and failure modes so replacement or mocking during testing is straightforward

Example use cases

• Web API: controllers call application use cases; HTTP layer is an adapter that translates requests to input ports and responses from output ports
• Batch job: scheduler adapter triggers use cases; persistence and external APIs are adapters implemented separately from domain
• Event-driven service: message consumer adapter converts events to input ports; outputs publish via messaging adapters
• Refactor legacy DAO logic into adapters so domain logic can be extracted and validated with unit tests
• Multi-database support: implement separate persistence adapters behind the same repository port to swap stores without domain changes

FAQ