Architecture Paradigm Hexagonal
Structure a solo builder’s backend so domain logic stays testable while databases, APIs, and UIs plug in through ports and adapters.
Overview
Architecture Paradigm Hexagonal is an agent skill most often used in Build (also Ship, Operate) that applies ports-and-adapters architecture to isolate domain logic from infrastructure for testability and swappable integ
Install
npx skills add https://github.com/athola/claude-night-market --skill architecture-paradigm-hexagonalWhat is this skill?
- Separates inbound driver ports (UI, CLI, jobs) from outbound driven ports (DB, messaging, third parties)
- Keeps domain logic stable when you swap frameworks, databases, or delivery surfaces
- Supports mock-driven testing by replacing slow or complex infrastructure with test doubles
- Documents when port/adapter overhead is wrong for scripts and throwaway prototypes
- Guides adoption starting with explicit domain port definitions before adapter implementations
Adoption & trust: 1 installs on skills.sh; 304 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
Your agent keeps mixing SQL, HTTP, and UI concerns into business rules, so every infra change breaks tests and forces wide refactors.
Who is it for?
Indie SaaS or API backends where you will change storage, messaging, or UI channels but want one stable domain core.
Skip if: Tiny scripts, one-off prototypes, or tools with no external dependencies where ports and adapters add ceremony without payoff.
When should I use this skill?
Designing systems where testability and port/adapter separation are priorities, or isolating business logic from external dependencies.
What do I get? / Deliverables
You get a port/adapter map and implementation guidance so domain code stays stable, adapters swap cleanly, and core behavior tests without real infrastructure.
- Inbound and outbound port inventory aligned to domain use cases
- Adapter placement plan and testing strategy using infrastructure substitutes
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Hexagonal design is where indie products commit to backend shape—ports, adapters, and domain isolation—before integrations harden. Backend subphase is the canonical shelf for architecture that separates core logic from infrastructure and external services.
Where it fits
Define driver and driven ports before wiring Prisma, Stripe, and a Next.js UI into a new billing service.
Replace Postgres adapters with in-memory fakes so CI validates pricing rules without a database.
Swap an email provider by implementing a new outbound adapter without touching subscription domain code.
How it compares
Use for deliberate boundary design instead of letting the agent generate a monolithic service with framework calls inside domain classes.
Common Questions / FAQ
Who is architecture-paradigm-hexagonal for?
Solo builders and small teams designing backends for SaaS, APIs, or agent services who care about testability and swapping databases or integrations without rewriting core logic.
When should I use architecture-paradigm-hexagonal?
During Build when sketching backend structure; again in Ship when tests need mocks instead of live DBs; and in Operate when migrating infrastructure or adding third-party integrations behind clear outbound ports.
Is architecture-paradigm-hexagonal safe to install?
It is architectural guidance only—review the Security Audits panel on this skill’s page before installing any package from the same repo.
SKILL.md
READMESKILL.md - Architecture Paradigm Hexagonal
# The Hexagonal (Ports & Adapters) Paradigm ## When To Use - Isolating business logic from external dependencies - Systems needing swappable adapters for testing ## When NOT To Use - Small scripts or utilities without external dependencies - Prototypes where port/adapter abstraction adds overhead ## When to Employ This Paradigm - When you anticipate frequent changes to databases, frameworks, or user interfaces and need the core domain logic to remain stable. - When testing the core application requires mocking complex or slow infrastructure components. - When the development team needs to provide clear inbound and outbound interfaces for third-party integrations. ## Adoption Steps 1. **Define Domain Ports**: Identify all interactions with the core domain. Define inbound "driver ports" for actors that initiate actions (e.g., UI, CLI, automated jobs) and outbound "driven ports" for services the application consumes (e.g., database, message bus, external APIs). Express these ports as formal interfaces. 2. **Implement Adapters at the Edge**: For each external technology, create an "adapter" that implements a port's interface. Keep the core domain entirely ignorant of the specific frameworks or libraries used in the adapters. 3. **Aggregate Use Cases**: Organize the application's functionality into services that are built around business capabilities. These services orchestrate calls to the domain through the defined ports. 4. **Implement Contract Testing**: validate that each adapter correctly honors the expectations of the port it implements. Use contract tests or consumer-driven contract tests to validate this behavior. 5. **Enforce Dependency Rules**: The most critical rule is that only adapters may have dependencies on external frameworks. Enforce this with automated architecture tests or static analysis rules. ## Key Deliverables - An Architecture Decision Record (ADR) that formally names the ports, their corresponding adapters, and the dependency policies. - A set of port interface definitions, stored with the core domain module. - A suite of contract tests for each adapter, alongside unit tests for the domain and application services. - Architectural diagrams showing the inbound and outbound data flows, for use by operations teams and architecture reviewers. ## Risks & Mitigations - **Port/Interface Bloat**: - **Mitigation**: An excessive number of ports can increase maintenance overhead. Group related operations into more cohesive, higher-level ports, often organized around domain aggregates. - **Leaky Abstractions**: - **Mitigation**: If a port's interface exposes details about the transport layer (e.g., HTTP headers), it is a "leaky abstraction." Refactor these interfaces to use domain-centric Data Transfer Objects (DTOs) instead. - **Adapter Drift**: - **Mitigation**: An adapter can become out-of-sync with the external technology it represents (e.g., database schema changes). Schedule regular, automated validation of adapters, such as verifying that SQL migrations still align with the expectations of the persistence port. ## Concrete Components These vocabulary items name the concrete tools and abstractions that show up when the paradigm is implemented. They are not required dependencies and they are not part of the skill's ``tools:`` frontmatter (which is reserved for Claude Code tool restrictions). Use this list to disambiguate during