# guinetik/hexafun architecture

> Architecture diagram of the GitHub repository guinetik/hexafun, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guinetik/hexafun
- Repository: https://github.com/guinetik/hexafun

## Overview

##### Project type and purpose
- From the README and file tree, HexaFun is not a web-app or microservice but a Java framework/library implementing a functional, declarative DSL for building Hexagonal-Architecture applications.
- It provides core DSL classes (`HexaApp`, `UseCaseBuilder`, `UseCase`, etc.), functional primitives (`Result`), testing support, and example applications (manual and todo).

##### File structure
- Top level
- pom.xml → Maven coordinates; JDK17+
- src/main/java/com/guinetik/hexafun
- Core packages (src/main/java/com/guinetik/hexafun):
- `hexa` → hexagonal contracts (InputPort, OutputPort, UseCase, ValidationPort, builder steps)
- `fun` → functional primitives (Result)
- root package → DSL entry point (`HexaFun`, `HexaApp`, `HexaAppImpl`)
- `testing` → test-DSL (HexaTest, UseCaseTest, MockAdapters)
- `examples` → sample apps (“manual” DSL example, “todo” example)
- Tests mirror these core packages.

##### README for additional insights
Driving Adapter → Input Port (UseCase) → Business Logic / Domain Model → Output Ports → Adapters
- The DSL allows you to define pipelines via `.from().to().and()` that compile into UseCase objects within a `HexaApp`.

##### Detail without overthinking
- Builder → registry → execution pipeline.
- Don’t worry about exhaustive Java-class listing; group related classes into logical components (e.g., “UseCase Builder” for all builder step classes).

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "External Drivers"
    direction TB
    DrivingAdapters["Driving Adapters\n(CLI, REST, Kafka, Event Listeners)"]:::external
  end

  subgraph "HexaFun Core Library"
    direction TB
    CoreDSL["DSL Entry Point\nHexaFun.dsl()"]:::core
    UseCaseBuilder["UseCase Builder\n(from→validation→output)"]:::core
    Contracts["Hexagonal Contracts\nInputPort, ValidationPort,\nUseCase, OutputPort"]:::core
    Engine["UseCase Engine & Registry\nHexaApp / HexaAppImpl"]:::core
    Primitives["Functional Primitives\nResult<T>"]:::core
  end

  subgraph "User Logic & Adapters"
    direction TB
    Domain["Domain Logic\nUser-supplied pipeline functions"]:::user
    OutputAdapters["Output Adapters\nInMemory, DB, Email, Messaging"]:::user
  end

  subgraph "Testing Module"
    direction TB
    Testing["Testing Framework\nHexaTest, UseCaseTest, MockAdapters"]:::test
  end

  subgraph "Example Applications"
    direction TB
    ManualExample["Manual Example App"]:::user
    TodoExample["Todo Example App"]:::user
  end

  %% Build-time DSL wiring
  CoreDSL -->|"defines use cases"| UseCaseBuilder
  UseCaseBuilder -->|"registers in"| Engine
  Contracts -- binds --> UseCaseBuilder
  Primitives --- Contracts

  %% Runtime invocation
  DrivingAdapters -->|"invoke(useCaseName,input)"| Engine
  Engine -->|"lookup & execute"| Contracts
  Contracts -->|"InputPort.from()"| Domain
  Domain -->|"to()/and() step"| Contracts
  Contracts -->|"OutputPort.emit()"| OutputAdapters
  Primitives -->|"carry success/failure"| Engine

  %% Testing overlay
  Testing -.->|"wraps/intercepts"| Engine
  Testing -.-> Domain
  Testing -.-> OutputAdapters

  %% Examples usage
  ManualExample -->|"uses DSL & Engine"| CoreDSL
  TodoExample -->|"uses DSL & Engine"| CoreDSL

  %% Click Events
  click CoreDSL "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/HexaFun.java"
  click Engine "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/HexaApp.java"
  click Engine "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/HexaAppImpl.java"
  click UseCaseBuilder "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/hexa/UseCaseBuilder.java"
  click UseCaseBuilder "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/hexa/UseCaseInputStep.java"
  click UseCaseBuilder "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/hexa/UseCaseValidationStep.java"
  click UseCaseBuilder "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/hexa/UseCaseOutputStep.java"
  click Contracts "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/hexa/InputPort.java"
  click Contracts "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/hexa/ValidationPort.java"
  click Contracts "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/hexa/UseCase.java"
  click Contracts "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/hexa/OutputPort.java"
  click Primitives "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/fun/Result.java"
  click Testing "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/testing/HexaTest.java"
  click Testing "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/testing/UseCaseTest.java"
  click Testing "https://github.com/guinetik/hexafun/blob/master/src/main/java/com/guinetik/hexafun/testing/MockAdapters.java"
  click ManualExample "https://github.com/guinetik/hexafun/tree/master/src/main/java/com/guinetik/hexafun/examples/manual/"
  click TodoExample "https://github.com/guinetik/hexafun/tree/master/src/main/java/com/guinetik/hexafun/examples/todo/"

  %% Styles
  classDef core fill:#D6EAF8,stroke:#3498DB,color:#154360;
  classDef external fill:#F2F3F4,stroke:#95A5A6,color:#2C3E50;
  classDef user fill:#D5F5E3,stroke:#27AE60,color:#145A32;
  classDef test fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
```
