# Hexagonal Architecture (hexagonal-architecture)

> Designs, implements and refactors Ports & Adapters systems so business logic stays independent of frameworks, transport and persistence.

- Category: [Architecture](https://www.myskills.tools/en/categories/architecture/)
- Source: Community · Affaan Mustafa
- Repository: https://github.com/affaan-m/ECC/tree/main/skills/hexagonal-architecture (commit d29cf65)
- SKILL.md: https://github.com/affaan-m/ECC/blob/main/skills/hexagonal-architecture/SKILL.md
- Install command: `npx skills add affaan-m/ECC --skill hexagonal-architecture`
- License: MIT
- Compatible with: Claude Code, Codex, Cursor, Copilot, OpenCode
- Permissions: read-repo ✓, write-files ✓, shell ✗, network ✗
- Status: Scan passed
- A rule scan cannot catch every risk. Read this skill's SKILL.md and check its permissions before installing.

## Core rule

Dependencies always point inward: the domain depends on nothing external, and adapters implement ports at the edges.

## Execution Phases

1. **Model a use case boundary** — Define one use case with clear input and output DTOs, keeping transport details like req or GraphQL context outside.
2. **Define outbound ports first** — Model every side effect, such as persistence, external calls, logging or clock, as a port that describes a capability, not a technology.
3. **Orchestrate the use case** — The use case receives ports via constructor or arguments, validates invariants, coordinates domain rules and returns plain data.
4. **Adapters and wiring** — Build inbound and outbound adapters at the edge with mapping kept inside them, and wire everything in a single composition root.
5. **Test per boundary** — Unit test use cases with fake ports and adapters against real infrastructure; migrate existing systems slice by slice, never as a big-bang rewrite.

## Permissions (summarised from SKILL.md)

| Capability | Needed | Details |
|---|---|---|
| File writes | Required | Creates or refactors domain, use case, port, adapter, composition root and test code. |
| Command execution | Not required | The skill does not call for running commands. |
| Network outbound | Not required | No network access. |

## SKILL.md frontmatter (YAML)

```yaml
---
name: hexagonal-architecture
description: Design, implement, and refactor Ports & Adapters systems with clear domain boundaries, dependency inversion, and testable use-case orchestration across TypeScript, Java, Kotlin, and Go services. Use when introducing or refactoring toward Ports and Adapters, or when domain logic has become entangled with I/O.
metadata:
  origin: ECC
---
```

Home: https://www.myskills.tools/en/ · URL: https://www.myskills.tools/en/skills/hexagonal-architecture/