Skip to content
Skills Library
Programming · Building & coding

hexagonal

/hexagonal

Expert Hexagonal Architecture (Ports and Adapters) assistance covering driving/driven ports, infrastructure adapters, domain core isolation, and test stubbing. Use when decoupling domain logic from databases/HTTP frameworks, improving testability, or modernizing enterprise applications.

Licence
MIT
Last repository change
01.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 01.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Expert Hexagonal Architecture (Ports and Adapters) assistance covering driving/driven ports, infrastructure adapters, domain core isolation, and test stubbing. Use when decoupling domain logic from databases/HTTP frameworks, improving testability, or modernizing enterprise applications.

Original author description

Expert Hexagonal Architecture (Ports and Adapters) assistance covering driving/driven ports, infrastructure adapters, domain core isolation, and test stubbing. Use when decoupling domain logic from databases/HTTP frameworks, improving testability, or modernizing enterprise applications.

How it works

  1. When to Use
  2. Quick Start
  3. Core Concepts
  4. Common Patterns
  5. Best Practices
  6. Troubleshooting
  7. References
Original SKILL.md headings · 162 lines, 693 words
SKILL.md preview
---
name: hexagonal
description: Expert Hexagonal Architecture (Ports and Adapters) assistance covering driving/driven ports, infrastructure adapters, domain core isolation, and test stubbing. Use when decoupling domain logic from databases/HTTP frameworks, improving testability, or modernizing enterprise applications.
---

# Hexagonal Architecture (Ports and Adapters)

Hexagonal Architecture aims to create a loosely coupled application component that can easily connect to their software environment by "ports" and "adapters". It treats the database, the web UI, and external APIs as interchangeable "details" (infrastructure).

## When to Use

- **Core Business Logic Isolation**: Keeping domain models completely pure and independent of database choices, web frameworks, and messaging tools.
- **Pluggable Architecture**: Systems where components (e.g. storage engine, notification providers, payment gateways) must be easily swappable.
- **Automated Regression Testing**: Running full business scenario tests with fast, zero-dependency in-memory adapters.
- **Microservice Reusability**: Allowing the exact same business core to be driven by an HTTP REST controller, a gRPC server, and a CLI simultaneously.

## Quick Start

```go
// --- CORE (Inside the Hexagon) ---

// Port (Driver Port - Input)
type UserService interface {
    Register(name string) error
}

// Port (Driven Port - Output)
type UserRepository interface {
    Save(user User) error
}

// Application Service (Implementation)
type UserServiceImpl struct {
    repo UserRepository
}

func (s *UserServiceImpl) Register(name string) error {
    return s.repo.Save(User{Name: name})
}

// --- ADAPTERS (Outside the Hexagon) ---

// Driving Adapter (REST API)
func HandleRegister(w http.ResponseWriter, r *http.Request, svc UserService) {
    svc.Register(r.FormValue("name"))
}

// Driven Adapter (Postgres)
type PostgresRepo struct { db *sql.DB }
func (r *PostgresRepo) Save(u User) error { ... }
```

## Core Concepts

### Ports and Adapters Topology

The application core sits at the center; Driving Ports receive input from the outside world; Driven Ports communicate with infrastructure:

```text
[ HTTP Controller ] ──(Driving Port)──→ [ APPLICATION CORE ] ──(Driven Port)──→ [ Postgres Adapter ]
[ CLI Command ]     ──(Driving Port)──→ [ APPLICATION CORE ] ──(Driven Port)──→ [ Mock DB Adapter ]
```

### Driving Port & Primary Adapter

The driving port defines what the application can do:

```typescript
// core/ports/driving/register-user.port.ts
export interface RegisterUserCommand {
  email: string;
  fullName: string;
}

export interface RegisterUserUseCase {
  execute(command: RegisterUserCommand): Promise<string>;
}
```

```typescript
// adapters/driving/http/user.controller.ts (Primary Adapter)
export class UserController {
  constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

  async handlePost(req: Request, res: Response) {
    const userId = await this.registerUserUseCase.execute(req.body);
    res.status(201).json({ id: userId });
  }
}
```

### Driven Port & Secondary Adapter

The driven port defines external capabilities needed by the core:

```typescript
// core/ports/driven/notification.port.ts
export interface NotificationPort {
  sendWelcomeEmail(email: string, name: string): Promise<void>;
}

// adapters/driven/resend-email.adapter.ts (Secondary Adapter)
export class ResendEmailAdapter implements NotificationPort {
  async sendWelcomeEmail(email: string, name: string) {
    await resend.emails.send({
      to: email,
      subject: `Welcome, ${name}!`,
      from: "app@example.com",
    });
  }
}
```

## Common Patterns

### Mock Adapter for Unit Testing Ports

**Problem**: Testing business core without spinning up actual databases or message brokers.  
**Solution**: Implement an in-memory stub that satisfies the driven port interface.

```typescript
// test/mocks/in-memory-order.repository.ts
export class InMemoryOrderRepository implements OrderRepositoryPort {
  private readonly items = new Map<string, Order>();

  async save(order: Order): Promise<void> {
    this.items.set(order.id, order);
  }

  async findById(id: string): Promise<Order | null> {
    return this.items.get(id) ?? null;
  }
}

// Unit test executes with zero I/O overhead:
const repo = new InMemoryOrderRepository();
const service = new OrderService(repo);
```

## Best Practices

**Do**:

- Define Ports as Interfaces Inside Core: Ensure driven ports are authored by the business domain team, not infrastructure engineers.
- Create In-Memory Adapters for Fast Testing: Implement mock adapters for all driven ports to enable sub-second test suite runs.
- Keep Domain Core Pure: Disallow any external library imports in the domain core (except language utilities).
- Use Dependency Injection: Bind ports to concrete adapters at application bootstrap time.

**Don't**:

- Let infrastructure types enter the domain: Map incoming database models and HTTP requests to domain types inside adapters.
- Bypass the ports: Never allow driving adapters (controllers) to communicate directly with driven adapters (databases).
- Over-engineer simple utility services: For simple scripts or read-only tools, Hexagonal Architecture adds unnecessary complexity.

## Troubleshooting

| Error        | Cause                                    | Solution                                                 |
| :----------- | :--------------------------------------- | :------------------------------------------------------- |
| `Leakage`    | Logic depends on specific library types. | Wrap external types in domain-specific DTOs/Interfaces.  |
| `Complexity` | Too many interfaces for simple logic.    | Start with a simple Service/Repository split and evolve. |

## References

- [Alistair Cockburn's Original Paper](https://alistair.cockburn.us/hexagonal-architecture/)
- [Hexagonal Architecture in Go](https://medium.com/@matiasvarela/hexagonal-architecture-in-go-cfd4e436bd57)

Versions

RepositoryScoreLicence
This page · G1Joshi/Agent-Skills100MIT
arxdsilva/ai-loops100MIT
Tyler-R-Kendrick/agent-skills100MIT

Database snapshot: 13.11.2026 · package version a5ae8ada895a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ddd-architecture-hexagonal
    Comprehensive guidance for Hexagonal Architecture (Ports & Adapters) — Alistair Cockburn's hexagonal architecture with domain core, port definitions, adapter implementations, and full Java/Spring Boot implementation steps. Covers primary/driving adapters, secondary/driven…
  • 100hexagonal-clean-onion-architecture
    Use this skill when isolating core domain business logic from external frameworks, databases, and transport layers via ports & adapters.
  • 100hexagonal-architecture
    Use when structuring a Symfony app with ports & adapters / clean architecture — keeping the domain framework-free, defining interfaces (ports) in the domain and implementations (adapters) in infrastructure. Use when the task mentions hexagonal, ports/adapters, or "keep the domain pure".
  • 95hexagonal-architecture
    Use when the user or project explicitly adopts hexagonal (ports and adapters) architecture — a README, CLAUDE.md, or ADR that says so is the opt-in. Once a project has opted in, load this for every code change in it, not only architecture work — a new feature, a transport or SDK…
  • 100hexagonal-architecture
    Use when the project follows hexagonal (ports & adapters) architecture. Prevents domain code from depending on Spring or JPA. Use when you see packages like domain/, application/, infrastructure/, or adapters/ in the project structure.
  • 100hexagonal-architecture
    Use when the project follows hexagonal (ports & adapters) architecture. Prevents domain code from depending on Spring or JPA. Use when you see packages like domain/, application/, infrastructure/, or adapters/ in the project structure.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.