hexagonal-layers

Guides layer placement and dependency rules for hexagonal ports-and-adapters architecture.

1|Updated May 4, 2026
One-click install
npx skills add https://github.com/wesbragagt/nixos-config --skill hexagonal-layers-wesbragagt
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hexagonal-layers
Source: https://github.com/wesbragagt/nixos-config/tree/main/home/skills/hexagonal-layers
Command: npx skills add https://github.com/wesbragagt/nixos-config --skill hexagonal-layers-wesbragagt

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When building or reviewing code that follows hexagonal architecture, developers often struggle to decide where a piece of logic belongs — domain, port, adapter, or composition root — and accidentally violate the dependency rule by letting the domain import frameworks or infrastructure. ## Core Features & Use Cases - Layer Reference: Defines the responsibilities of the domain (entities, value objects, aggregates, domain services, domain events), input/output ports, input/output adapters, and the composition root. - Placement Guide & Checklists: Provides a quick lookup table for "where does X go?" questions, an entity-vs-value-object decision checklist, and guidance on when hexagonal architecture is worth using. - Anti-Pattern Detection: Lists common mistakes such as business logic in adapters, framework imports in the domain, and leaking domain models through APIs. - Use Case: While reviewing a pull request, you notice a REST controller checking whether an order is cancellable. Use this Skill to confirm the rule belongs in the domain entity and that the controller should only map requests and responses. ## Quick Start Ask the assistant to review your service's package structure against hexagonal architecture layer rules and identify any dependency violations.

Frequently Asked Questions about hexagonal-layers

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure code with hexagonal architecture?

Organize code into four layers: a pure domain core with entities and value objects, ports defining input use cases and output contracts, adapters implementing those ports for frameworks and databases, and a composition root that wires everything together. All dependencies must point inward.

What is the difference between an entity and a value object?

An entity has a business-meaningful identity and changes over time while remaining the same thing, compared by ID. A value object is immutable, defined entirely by its attribute values, self-validating, and interchangeable with an identical copy.

Where should business logic go in ports and adapters architecture?

Business rules and validations belong in the domain layer, inside entities, value objects, or domain services. Adapters only translate data formats and handle framework concerns like HTTP status codes; any domain rule found in an adapter should be moved inward.

When should I not use hexagonal architecture?

Skip it for simple CRUD services, short-lived prototypes, thin database wrappers, or small teams with straightforward domains. The layering overhead is only justified by complex business rules, multiple I/O boundaries, and long-lived systems.

Why is my domain layer importing frameworks a problem?

Framework imports in the domain break the dependency rule, coupling business logic to infrastructure and preventing isolated testing. Domain tests should run with no database, HTTP server, or mocks; enforce this with architecture tests.