hexagonal-architecture
Master the Ports & Adapters pattern to isolate business logic from frameworks and infrastructure. This skill covers domain modeling, use-case orchestration, inbound and outbound port design, adapter implementation, and composition wiring across multiple languages.
Hexagonal Architecture teaches you to structure applications with clear domain boundaries, dependency inversion, and testable use cases.
AI-generated summary based on this skill's SKILL.md
Install
affaan-m/ECC/hexagonal-architecture · repository language: JavaScript
git clone https://github.com/affaan-m/ECC
cp -r ECC/skills/hexagonal-architecture ~/.claude/skills/hexagonal-architecturenpx skillfed install affaan-m/ECC/hexagonal-architectureFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do you implement hexagonal architecture with ports and adapters?
Hexagonal-architecture structures applications by isolating business logic at the core, surrounded by ports (interfaces defining contracts) and adapters (implementations connecting to external systems). Start by identifying your domain use cases, define inbound ports for incoming requests and outbound ports for external dependencies, then implement adapters that translate between your domain and frameworks like HTTP, databases, or message queues. This separation ensures your core logic remains testable and framework-agnostic.
What is the difference between inbound and outbound ports in hexagonal architecture?
In hexagonal-architecture, inbound ports expose your application's use cases to the outside world—they define how external actors trigger business logic. Outbound ports define contracts for external resources your domain needs, like databases or APIs. Inbound adapters (controllers, CLI handlers) call inbound ports; outbound adapters (repositories, HTTP clients) implement outbound ports. This bidirectional structure keeps dependencies pointing inward toward your domain.
How can you refactor existing services to decouple business logic from framework dependencies?
Hexagonal-architecture enables decoupling by extracting business logic into a framework-independent core. Identify tightly-coupled code, move it into use-case classes that depend only on domain objects and port interfaces, then create adapters wrapping your existing framework calls. Use dependency injection at a composition root to wire ports to adapters. This approach works across TypeScript, Java, Kotlin, and Go, allowing gradual migration without rewriting everything at once.
Why is hexagonal architecture beneficial for testing?
Hexagonal-architecture improves testability by isolating business logic from external dependencies. Since your use cases depend only on port interfaces, you can inject mock adapters during tests without touching real databases, APIs, or frameworks. Test boundaries align with clear domain separation, letting you verify use-case logic in isolation. This design eliminates the need for complex test infrastructure and makes tests faster, more reliable, and easier to maintain.
How do you apply hexagonal architecture patterns across TypeScript, Java, Kotlin, and Go?
Hexagonal-architecture principles remain consistent across languages, though implementation details vary. In TypeScript, use interfaces and dependency injection frameworks; in Java/Kotlin, leverage annotations and Spring; in Go, use interfaces and struct composition. The core pattern—domain core, inbound/outbound ports, adapters—translates directly. Language-specific tooling differs, but the architectural intent of isolating business logic and managing dependencies through ports stays the same.
What role does the composition root play in hexagonal architecture?
The composition root in hexagonal-architecture is where you wire all dependencies together—instantiating adapters, injecting them into ports, and configuring the application for startup. It's the single place where your framework and infrastructure concerns live, keeping them out of your domain core. By centralizing composition, you maintain clean separation of concerns and make it easy to swap adapters or change configurations without touching business logic.
SKILL.md
rendered from the published skill — quoted content, verbatim
Hexagonal Architecture
Hexagonal architecture (Ports and Adapters) keeps business logic independent from frameworks, transport, and persistence details. The core app depends on abstract ports, and adapters implement those ports at the edges.
When to Use
- Building new features where long-term maintainability and testability matter.
- Refactoring layered or framework-heavy code where domain logic is mixed with I/O concerns.
- Supporting multiple interfaces for the same use case (HTTP, CLI, queue workers, cron jobs).
- Replacing infrastructure (database, external APIs, message bus) without rewriting business rules.
Use this skill when the request involves boundaries, domain-centric design, refactoring tightly coupled services, or decoupling application logic from specific libraries.
Core Concepts
- Domain model: Business rules and entities/value objects. No framework imports.
- **Use cases
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
skills/hexagonal-architecture/SKILL.md