SkillAgentSearch skills...

nw-fp-hexagonal-architecture

Hexagonal architecture patterns with pure core and side-effect shell for functional codebases

Install / Use

npx skills add nWave-ai/nWave --skill nw-fp-hexagonal-architecture

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

87/100

Supported Platforms

Universal

Tags

Our assessment of nw-fp-hexagonal-architecture

nw-fp-hexagonal-architecture scores 87/100 on our quality scale, 2138th of 4,705 Development & Engineering skills we index (top 46%).

Its SKILL.md is 8.3 KB long, well organised into 16 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.

It has 617 GitHub stars, a meaningful sign that others use it.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so nw-fp-hexagonal-architecture is actively maintained.
  • Our last check on 2026-10-11 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-08. Automated pattern scan on 2026-10-08. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

nw-fp-hexagonal-architecture compared with similar skills

All 4 of these similar skills score higher than nw-fp-hexagonal-architecture; compare them before choosing.

SkillScoreStarsUpdatedFormat
nw-fp-hexagonal-architecture (this skill)by nWave-ai876172mo agoSKILL.md
taste-skillby Leonxlnx100120.0ktodayCLAUDE.md
hyperframesby heygen-com10088.2ktodayCLAUDE.md
ai-job-searchby ai-job-search-dev10073.0ktodayCLAUDE.md
claude-howtoby luongnv8910047.5k1d agoCLAUDE.md

Frequently asked questions

How do I install nw-fp-hexagonal-architecture?
Run npx skills add nWave-ai/nWave --skill nw-fp-hexagonal-architecture. The install tabs above show the steps for each supported agent.
Which AI agents does nw-fp-hexagonal-architecture work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is nw-fp-hexagonal-architecture safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is nw-fp-hexagonal-architecture still maintained?
The repository was last updated about 2 months ago, so nw-fp-hexagonal-architecture is actively maintained.

name: nw-fp-hexagonal-architecture agent: nw-functional-software-crafter description: Hexagonal architecture patterns with pure core and side-effect shell for functional codebases user-invocable: false disable-model-invocation: true

FP Hexagonal Architecture

Ports and adapters in functional programming. Structure applications with a pure core and side-effect shell.

Cross-references: fp-principles | fp-domain-modeling | fp-usable-design


1. The Natural Fit

[STARTER]

Functional architecture naturally implements ports and adapters. The paradigm's separation of pure functions from side effects IS the hexagonal boundary.

| OOP Concept | FP Equivalent | Why | |---|---|---| | Port (interface) | Function type signature / type alias | Port defines contract; function signature IS that contract | | Adapter (class) | Concrete function implementation | Adapter fulfills contract; matching function does same | | DI container | Function parameters / partial application | Dependencies passed as arguments, no container needed | | Domain service class | Module of pure functions | Related pure functions replace stateful service object | | Entity with behavior | Immutable data + functions operating on it | Data and behavior separated; functions transform immutable values |


2. Pure Core / Side-Effect Shell

[STARTER]

All business logic is pure; all side effects live at the system's edges.

The Sandwich Pattern: Read (impure) -> Decide (pure) -> Write (impure)

+--------------------------------------------------+
|  Side-Effect Shell (thin)                        |
|  - HTTP handlers, CLI, message consumers         |
|  - Database access, file I/O, network calls      |
|  - Reads data, calls core, writes results        |
|                                                  |
|  +--------------------------------------------+ |
|  |  Pure Core (large)                          | |
|  |  - Pure functions only                      | |
|  |  - Domain logic, validation, calculation    | |
|  |  - No I/O, no side effects                  | |
|  |  - Immutable data transformations           | |
|  +--------------------------------------------+ |
+--------------------------------------------------+

Dependency Rule: Shell may call core. Core never calls shell. Core is unaware of shell's existence.

Why: Pure core is trivially testable (no mocks, no setup, no teardown). Shell is thin and needs few integration tests.


3. Ports as Function Types

[STARTER]

A port is a function type signature describing a capability the domain needs:

FindOrder    : OrderId -> AsyncResult<Order option>
SaveOrder    : Order -> AsyncResult<unit>
SendEmail    : Email -> AsyncResult<unit>
GetPrice     : ProductCode -> Price
CheckExists  : ProductCode -> bool

When to define: Domain needs a capability involving I/O or external systems. Domain declares WHAT; adapter provides HOW.

Naming: Verb-noun. Name describes capability, not technology.


4. Adapters as Implementations

[STARTER]

An adapter is a concrete function matching a port's type signature:

PostgresOrderRepo.findOrder  : OrderId -> AsyncResult<Order option>
InMemoryOrderRepo.findOrder  : OrderId -> AsyncResult<Order option>

Both match the FindOrder port. Domain doesn't know which is used.


5. Dependency Injection via Functions

[STARTER] -> [INTERMEDIATE] -> [ADVANCED]

Decision Tree: How to Inject This Dependency?

How many dependencies does the function need?
  1-3 --> [STARTER] Functions as Parameters
  4-6 --> [INTERMEDIATE] Consider Environment Pattern or grouping
  7+  --> [ADVANCED] Capability Interfaces or Effect System
         (also: reconsider function responsibilities)

[STARTER] Functions as Parameters

Pass dependencies as function parameters. Partially apply at composition root.

placeOrder (findCustomer) (saveOrder) (rawOrder) = ...
placeOrderHandler = placeOrder Database.findCustomer Database.saveOrder

[INTERMEDIATE] Environment Pattern (Reader)

Dependencies in a record, provided once at top level. Use when parameter threading becomes painful (4+ deps).

placeOrder (rawOrder) = reader { env = ask(); env.findCustomer(rawOrder.customerId) ... }
placeOrder(rawOrder) |> runWith(productionEnv)

[ADVANCED] Capability Interfaces / Effect Systems

Abstract over effect types (tagless final) or use fine-grained effect tracking (ZIO, Koka). Use for large codebases with many effects.

Recommendation by Context

| Context | Approach | |---|---| | Small/medium codebase | Functions as parameters | | Large codebase, many effects | Capability interfaces or effect system | | Pragmatic TypeScript/F# | Functions as parameters + modules |


6. Pipeline Composition Through Architecture

[INTERMEDIATE]

Workflows flow through architecture as pipelines:

HTTP Request
  -> Parse (shell: impure)
  -> Validate (core: pure)
  -> Calculate (core: pure)
  -> Persist (shell: impure)
  -> Respond (shell: impure)

Each pure step is a function in the pipeline. Shell handles I/O at start and end.

Error-track pipelines: Each step returns Result type; pipeline short-circuits on first failure. See fp-domain-modeling.

Collect-all-errors: When you need ALL validation errors, use Applicative style. See fp-principles section 5.


7. Testing Strategy

[INTERMEDIATE]

| Layer | Test Type | Volume | Speed | Mocks | |---|---|---|---|---| | Pure core (domain) | Unit + Property-based | Many | Fast (ms) | None | | Composition root | Integration (wiring) | Few | Medium | None | | Adapters | Integration | Few per adapter | Slow | None (real deps) | | End-to-end | System tests | Very few | Slowest | None |

Key insight: Pure functions need no mocking. Input in, output out. Strongest practical argument for maximizing the pure core.

Property-based testing is the natural companion. Define rules that hold for all valid inputs. See fp-algebra-driven-design.


8. Side Effect Management Approaches

[ADVANCED]

| Approach | Enforcement | Granularity | Best For | |---|---|---|---| | Convention (discipline) | None | N/A | Any language, small teams | | IO Type (Haskell) | Compile-time | Binary (pure/impure) | Haskell | | Effect Systems (ZIO, Koka) | Compile-time | Per-effect | Large systems | | Pure Core / Shell | Architectural | Module-level | Any language, pragmatic |

IO actions as values: Side effects are descriptions of actions, not actions themselves. Can be stored, composed, and only execute when runtime reaches them.

Type-level effect tracking: Mark impure functions clearly -- through return types, naming conventions, or annotations. Even without compiler enforcement, the discipline applies.


9. Combining Patterns

Domain Wrappers + Smart Constructors (fp-domain-modeling)
        |
        v
Choice Types for State Machines -----> Error-Track Pipelines
        |                                       |
        v                                       v
Pure Core / Side-Effect Shell ---------> Functions as Parameters (DI)
        |                                       |
        v                                       v
Pipeline Composition <-----------------  Property-Based Testing

Worked Example: Place Order Workflow

-- Ports (function signatures)
FindCustomer : CustomerId -> AsyncResult<Customer>
SaveOrder    : Order -> AsyncResult<Unit>

-- Pure Core (domain logic)
validateOrder : RawOrder -> Result<ValidOrder, ValidationError>
priceOrder    : ValidOrder -> PricedOrder

-- Pipeline (Pure Core + Error Pipeline + DI via parameters)
placeOrder (findCustomer) (saveOrder) (raw) =
    raw
    |> validateOrder                     -- pure, Result
    |> bindAsync (o -> findCustomer o.customerId |> map (c -> (o, c)))  -- port call
    |> map (fun (o, c) -> priceOrder o)  -- pure
    |> bindAsync saveOrder               -- port call

Recommended learning sequence:

[STARTER]: Pure Core/Shell -> Domain Wrappers -> Smart Constructors -> Pipeline Composition

[INTERMEDIATE]: Choice Types -> Error-Track Pipelines -> Functions as Parameters -> Property Testing

[ADVANCED]: Capability Interfaces -> Effect Systems -> Collect-All-Errors Validation

Related Skills

View on GitHub
GitHub Stars617
CategoryDevelopment
Updated2mo ago
Forks63

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions