Nw fp hexagonal architecture

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