common-hexagonal-architecture

Apply Hexagonal Architecture (also known as Ports & Adapters) to keep domain logic independent of frameworks, databases, messaging systems, and UIs within a single service boundary.

When to use

Use this skill when:

• Designing or restructuring the internal architecture of a service or module
• Ensuring domain/business logic is testable without infrastructure dependencies
• Introducing a new external integration (database, API, queue, file system)
• Reviewing code to verify that infrastructure concerns do not leak into the core
• Refactoring a layered or "big ball of mud" codebase toward cleaner boundaries

Core concepts

The Hexagon (Application Core)

The hexagon contains all business logic and domain rules. It knows nothing about the outside world — no HTTP, no SQL, no file I/O. It communicates exclusively through ports.