Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat: add hexagonal architecture SKILL. (#1034)

Divya Somashekar9b611f1b3764
diff --git a/skills/hexagonal-architecture/SKILL.md b/skills/hexagonal-architecture/SKILL.md
new file mode 100644
index 000000000..29ab17c44
--- /dev/null
+++ b/skills/hexagonal-architecture/SKILL.md
@@ -0,0 +1,276 @@
+---
+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.
+origin: ECC
+---
+
+# 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 (application layer)**: Orchestrate domain behavior and workflow steps.
+- **Inbound ports**: Contracts describing what the application can do (commands/queries/use-case interfaces).
+- **Outbound ports**: Contracts for dependencies the application needs (repositories, gateways, event publishers, clock, UUID, etc.).
+- **Adapters**: Infrastructure and delivery implementations of ports (HTTP controllers, DB repositories, queue consumers, SDK wrappers).
+- **Composition root**: Single wiring location where concrete adapters are bound to use cases.
+
+Outbound port interfaces usually live in the application layer (or in domain only when the abstraction is truly domain-level), while infrastructure adapters implement them.
+
+Dependency direction is always inward:
+
+- Adapters -> application/domain
+- Application -> port interfaces (inbound/outbound contracts)
+- Domain -> domain-only abstractions (no framework or infrastructure dependencies)
+- Domain -> nothing external
+
+## How It Works
+
+### Step 1: Model a use case boundary
+
+Define a single use case with a clear input and output DTO. Keep transport details (Express `req`, GraphQL `context`, job payload wrappers) outside this boundary.
+
+### Step 2: Define outbound ports first
+
+Identify every side effect as a port:
+
+- persistence (`UserRepositoryPort`)
+- external calls (`BillingGatewayPort`)
+- cross-cutting (`LoggerPort`, `ClockPort`)
+
+Ports should model capabilities, not technologies.
+
+### Step 3: Implement the use case with pure orchestration
+
+Use case class/function receives ports via constructor/arguments. It validates application-level invariants, coordinates domain rules, and returns plain data structures.
+
+### Step 4: Build adapters at the edge
+
+- Inbound adapter converts protocol input to use-case input.
+- Outbound adapter maps app contracts to concrete APIs/ORM/query builders.
+- Mapping stays in adapters, not inside use cases.
+
+### Step 5: Wire everything in a composition root
+
+Instantiate adapters, then inject them into use cases. Keep this wiring centralized to avoid hidden service-locator behavior.
+
+### Step 6: Test per boundary
+
+- Unit test use cases with fake ports.
+- Integration test adapters with real infra dependencies.
+- E2E test user-facing flows through inbound adapters.
+
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+ Client["Client (HTTP/CLI/Worker)"] --> InboundAdapter["Inbound Adapter"]
+ InboundAdapter -->|"calls"| UseCase["UseCase (Application Layer)"]
+ UseCase -->|"uses"| OutboundPort["OutboundPort (Interface)"]
+ OutboundAdapter["Outbound Adapter"] -->|"implements"| OutboundPort
+ OutboundAdapter --> ExternalSystem["DB/API/Queue"]
+ UseCase --> DomainModel["DomainModel"]
+```
+
+## Suggested Module Layout
+
+Use feature-first organization with explicit boundaries:
+
+```text
+src/
+ features/
+ orders/
+ domain/
+ Order.ts
+ OrderPolicy.ts
+ application/
+ ports/
+ inbound/
+ CreateOrder.ts
+ outbound/
+ OrderRepositoryPort.ts
+ PaymentGatewayPort.ts
+ use-cases/
+ CreateOrderUseCase.ts
+ adapters/
+ inbound/
+ http/
+ createOrderRoute.ts
+ outbound/
+ postgres/
+ PostgresOrderRepository.ts
+ stripe/
+ StripePaymentGateway.ts
+ composition/
+ ordersContainer.ts
+```
+
+## TypeScript Example
+
+### Port definitions
+
+```typescript
+export interface OrderRepositoryPort {
+ save(order: Order): Promise<void>;
+ findById(orderId: string): Promise<Order | null>;
+}
+
+export interface PaymentGatewayPort {
+ authorize(input: { orderId: string; amountCents: number }): Promise<{ authorizationId: string }>;
+}
+```
+
+### Use case
+
+```typescript
+type CreateOrderInput = {
+ orderId: string;
+ amountCents: number;
+};
+
+type CreateOrderOutput = {
+ orderId: string;
+ authorizationId: string;
+};
+
+export class CreateOrderUseCase {
+ constructor(
+ private readonly orderRepository: OrderRepositoryPort,
+ private readonly paymentGateway: PaymentGatewayPort
+ ) {}
+
+ async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
+ const order = Order.create({ id: input.orderId, amountCents: input.amountCents });
+
+ const auth = await this.paymentGateway.authorize({
+ orderId: order.id,
+ amountCents: order.amountCents,
+ });
+
+ // markAuthorized returns a new Order instance; it does not mutate in place.
+ const authorizedOrder = order.markAuthorized(auth.authorizationId);
+ await this.orderRepository.save(authorizedOrder);
+
+ return {
+ orderId: order.id,
+ authorizationId: auth.authorizationId,
+ };
+ }
+}
+```
+
+### Outbound adapter
+
+```typescript
+export class PostgresOrderRepository implements OrderRepositoryPort {
+ constructor(private readonly db: SqlClient) {}
+
+ async save(order: Order): Promise<void> {
+ await this.db.query(
+ "insert into orders (id, amount_cents, status, authorization_id) values ($1, $2, $3, $4)",
+ [order.id, order.amountCents, order.status, order.authorizationId]
+ );
+ }
+
+ async findById(orderId: string): Promise<Order | null> {
+ const row = await this.db.oneOrNone("select * from orders where id = $1", [orderId]);
+ return row ? Order.rehydrate(row) : null;
+ }
+}
+```
+
+### Composition root
+
+```typescript
+export const buildCreateOrderUseCase = (deps: { db: SqlClient; stripe: StripeClient }) => {
+ const orderRepository = new PostgresOrderRepository(deps.db);
+ const paymentGateway = new StripePaymentGateway(deps.stripe);
+
+ return new CreateOrderUseCase(orderRepository, paymentGateway);
+};
+```
+
+## Multi-Language Mapping
+
+Use the same boundary rules across ecosystems; only syntax and wiring style change.
+
+- **TypeScript/JavaScript**
+ - Ports: `application/ports/*` as interfaces/types.
+ - Use cases: classes/functions with constructor/argument injection.
+ - Adapters: `adapters/inbound/*`, `adapters/outbound/*`.
+ - Composition: explicit factory/container module (no hidden globals).
+- **Java**
+ - Packages: `domain`, `application.port.in`, `application.port.out`, `application.usecase`, `adapter.in`, `adapter.out`.
+ - Ports: interfaces in `application.port.*`.
+ - Use cases: plain classes (Spring `@Service` is optional, not required).
+ - Composition: Spring config or manual wiring class; keep wiring out of domain/use-case classes.
+- **Kotlin**
+ - Modules/packages mirror the Java split (`domain`, `application.port`, `application.usecase`, `adapter`).
+ - Ports: Kotlin interfaces.
+ - Use cases: classes with constructor injection (Koin/Dagger/Spring/manual).
+ - Composition: module definitions or dedicated composition functions; avoid service locator patterns.
+- **Go**
+ - Packages: `internal/<feature>/domain`, `application`, `ports`, `adapters/inbound`, `adapters/outbound`.
+ - Ports: small interfaces owned by the consuming application package.
+ - Use cases: structs with interface fields plus explicit `New...` constructors.
+ - Composition: wire in `cmd/<app>/main.go` (or dedicated wiring package), keep constructors explicit.
+
+## Anti-Patterns to Avoid
+
+- Domain entities importing ORM models, web framework types, or SDK clients.
+- Use cases reading directly from `req`, `res`, or queue metadata.
+- Returning database rows directly from use cases without domain/application mapping.
+- Letting adapters call each other directly instead of flowing through use-case ports.
+- Spreading dependency wiring across many files with hidden global singletons.
+
+## Migration Playbook
+
+1. Pick one vertical slice (single endpoint/job) with frequent change pain.
+2. Extract a use-case boundary with explicit input/output types.
+3. Introduce outbound ports around existing infrastructure calls.
+4. Move orchestration logic from controllers/services into the use case.
+5. Keep old adapters, but make them delegate to the new use case.
+6. Add tests around the new boundary (unit + adapter integration).
+7. Repeat slice-by-slice; avoid full rewrites.
+
+### Refactoring Existing Systems
+
+- **Strangler approach**: keep current endpoints, route one use case at a time through new ports/adapters.
+- **No big-bang rewrites**: migrate per feature slice and preserve behavior with characterization tests.
+- **Facade first**: wrap legacy services behind outbound ports before replacing internals.
+- **Composition freeze**: centralize wiring early so new dependencies do not leak into domain/use-case layers.
+- **Slice selection rule**: prioritize high-churn, low-blast-radius flows first.
+- **Rollback path**: keep a reversible toggle or route switch per migrated slice until production behavior is verified.
+
+## Testing Guidance (Same Hexagonal Boundaries)
+
+- **Domain tests**: test entities/value objects as pure business rules (no mocks, no framework setup).
+- **Use-case unit tests**: test orchestration with fakes/stubs for outbound ports; assert business outcomes and port interactions.
+- **Outbound adapter contract tests**: define shared contract suites at port level and run them against each adapter implementation.
+- **Inbound adapter tests**: verify protocol mapping (HTTP/CLI/queue payload to use-case input and output/error mapping back to protocol).
+- **Adapter integration tests**: run against real infrastructure (DB/API/queue) for serialization, schema/query behavior, retries, and timeouts.
+- **End-to-end tests**: cover critical user journeys through inbound adapter -> use case -> outbound adapter.
+- **Refactor safety**: add characterization tests before extraction; keep them until new boundary behavior is stable and equivalent.
+
+## Best Practices Checklist
+
+- Domain and use-case layers import only internal types and ports.
+- Every external dependency is represented by an outbound port.
+- Validation occurs at boundaries (inbound adapter + use-case invariants).
+- Use immutable transformations (return new values/entities instead of mutating shared state).
+- Errors are translated across boundaries (infra errors -> application/domain errors).
+- Composition root is explicit and easy to audit.
+- Use cases are testable with simple in-memory fakes for ports.
+- Refactoring starts from one vertical slice with behavior-preserving tests.
+- Language/framework specifics stay in adapters, never in domain rules.