# phunkie/effect architecture

> Architecture diagram of the GitHub repository phunkie/effect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phunkie/effect
- Repository: https://github.com/phunkie/effect

## Overview

Phunkie Effect is a PHP functional effects library centered on lazy IO values: application code builds effect descriptions, composes them, and runs them at an application boundary. Its domain capabilities include sequential composition, error recovery, resource safety, parallel combination, and asynchronous/racing execution; IOApp adds command-line parsing and process output. The graph preserves documented capabilities even where implementation excerpts are absent. Edges are limited to relationships shown in excerpts, the source index, or README; unsampled resource and helper internals are not inferred.

Main entry points: [`src/IO/IO.php`](https://github.com/phunkie/effect/blob/main/src/IO/IO.php) (Lazy IO), [`src/IO/IOApp/Options.php`](https://github.com/phunkie/effect/blob/main/src/IO/IOApp/Options.php) (Option Parser), [`src/Concurrent/ExecutionContext.php`](https://github.com/phunkie/effect/blob/main/src/Concurrent/ExecutionContext.php) (Execution Context), [`src/Ops/IO/ConcurrentOps.php`](https://github.com/phunkie/effect/blob/main/src/Ops/IO/ConcurrentOps.php) (Race And Timeout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_effects["IO Effects"]
  node_io["Lazy IO<br/>[IO.php]"]
  node_io_constructor["IO Constructors<br/>[io.php]"]
  node_resource["Resource Safety<br/>[Resource.php]"]
  node_exit_case["Exit Cases<br/>[ExitCase.php]"]
end

subgraph group_composition["Composition Ops"]
  node_functor_ops["Functor Ops<br/>[FunctorOps.php]"]
  node_applicative_ops["Applicative Ops<br/>[ApplicativeOps.php]"]
  node_monad_ops["Monad Ops<br/>[MonadOps.php]"]
  node_error_ops["Error Recovery<br/>[MonadErrorOps.php]"]
  node_parallel_ops["Parallel Ops<br/>[ParallelOps.php]"]
  node_parallel_type["Parallel Contract<br/>[Parallel.php]"]
end

subgraph group_concurrency["Concurrency"]
  node_concurrent_ops["Race And Timeout<br/>[ConcurrentOps.php]"]
  node_blocker["Blocking Work<br/>[Blocker.php]"]
  node_execution_context["Execution Context"]
  node_fiber_context["Fiber Context"]
  node_parallel_context["Thread Context"]
  node_async_handle["Async Handle<br/>[AsyncHandle.php]"]
  node_cancellable_handle["Cancellable Handle"]
  node_timeout_exception["Timeout Error"]
end

subgraph group_application["Application Runtime"]
  node_ioapp["IO App Entry<br/>[IOApp.php]"]
  node_options["Option Parser<br/>[Options.php]"]
  node_option_definition["Option Definitions"]
  node_option_format["Option Formats<br/>[OptionFormat.php]"]
  node_parsed_options["Parsed Options<br/>[ParsedOptions.php]"]
  node_app_error["CLI Errors<br/>[Error.php]"]
  node_app_functions["CLI Builders<br/>[ioapp.php]"]
  node_console_functions["Console Effects<br/>[console.php]"]
end

node_developer(("Application Code"))

node_developer -->|"constructs effects"| node_io_constructor
node_io_constructor -->|"creates IO"| node_io
node_developer -->|"defines app"| node_ioapp
node_ioapp -->|"parses arguments"| node_options
node_options -->|"uses definitions"| node_option_definition
node_options -->|"checks formats"| node_option_format
node_options -->|"produces options"| node_parsed_options
node_options -->|"returns parse errors"| node_app_error
node_app_functions -->|"builds definitions"| node_options
node_io -->|"uses operations"| node_functor_ops
node_io -->|"uses operations"| node_applicative_ops
node_io -->|"uses operations"| node_monad_ops
node_io -->|"uses operations"| node_error_ops
node_io -->|"uses operations"| node_parallel_ops
node_io -->|"uses operations"| node_concurrent_ops
node_io -->|"defaults to"| node_fiber_context
node_io -->|"accepts context"| node_execution_context
node_parallel_ops -->|"requires context"| node_parallel_context
node_parallel_ops -->|"runs blockers"| node_blocker
node_parallel_ops -->|"combines values"| node_parallel_type
node_concurrent_ops -->|"dispatches blocking"| node_blocker
node_concurrent_ops -->|"dispatches effects"| node_execution_context
node_concurrent_ops -->|"polls and cancels"| node_cancellable_handle
node_concurrent_ops -->|"raises timeout"| node_timeout_exception
node_blocker -->|"delegates execution"| node_execution_context
node_execution_context -->|"returns handle"| node_async_handle
node_fiber_context -->|"implements context"| node_execution_context
node_fiber_context -->|"returns handle"| node_async_handle
node_parallel_context -->|"implements context"| node_execution_context
node_parallel_context -->|"returns handle"| node_cancellable_handle
node_parallel_context -->|"returns handle"| node_async_handle
node_ioapp -->|"returns program"| node_io
node_ioapp -.->|"writes output"| node_console_functions
node_io -.->|"supports resource safety"| node_resource
node_developer -->|"combines in parallel"| node_parallel_ops

click node_io "https://github.com/phunkie/effect/blob/main/src/IO/IO.php"
click node_io_constructor "https://github.com/phunkie/effect/blob/main/src/Functions/io.php"
click node_resource "https://github.com/phunkie/effect/blob/main/src/IO/Resource.php"
click node_exit_case "https://github.com/phunkie/effect/blob/main/src/IO/ExitCase.php"
click node_functor_ops "https://github.com/phunkie/effect/blob/main/src/Ops/IO/FunctorOps.php"
click node_applicative_ops "https://github.com/phunkie/effect/blob/main/src/Ops/IO/ApplicativeOps.php"
click node_monad_ops "https://github.com/phunkie/effect/blob/main/src/Ops/IO/MonadOps.php"
click node_error_ops "https://github.com/phunkie/effect/blob/main/src/Ops/IO/MonadErrorOps.php"
click node_parallel_ops "https://github.com/phunkie/effect/blob/main/src/Ops/IO/ParallelOps.php"
click node_parallel_type "https://github.com/phunkie/effect/blob/main/src/Cats/Parallel.php"
click node_concurrent_ops "https://github.com/phunkie/effect/blob/main/src/Ops/IO/ConcurrentOps.php"
click node_blocker "https://github.com/phunkie/effect/blob/main/src/Concurrent/Blocker.php"
click node_execution_context "https://github.com/phunkie/effect/blob/main/src/Concurrent/ExecutionContext.php"
click node_fiber_context "https://github.com/phunkie/effect/blob/main/src/Concurrent/FiberExecutionContext.php"
click node_parallel_context "https://github.com/phunkie/effect/blob/main/src/Concurrent/ParallelExecutionContext.php"
click node_async_handle "https://github.com/phunkie/effect/blob/main/src/Concurrent/AsyncHandle.php"
click node_cancellable_handle "https://github.com/phunkie/effect/blob/main/src/Concurrent/CancellableHandle.php"
click node_timeout_exception "https://github.com/phunkie/effect/blob/main/src/Concurrent/TimeoutException.php"
click node_ioapp "https://github.com/phunkie/effect/blob/main/src/IO/IOApp.php"
click node_options "https://github.com/phunkie/effect/blob/main/src/IO/IOApp/Options.php"
click node_option_definition "https://github.com/phunkie/effect/blob/main/src/IO/IOApp/OptionDefinition.php"
click node_option_format "https://github.com/phunkie/effect/blob/main/src/IO/IOApp/OptionFormat.php"
click node_parsed_options "https://github.com/phunkie/effect/blob/main/src/IO/IOApp/ParsedOptions.php"
click node_app_error "https://github.com/phunkie/effect/blob/main/src/IO/IOApp/Error.php"
click node_app_functions "https://github.com/phunkie/effect/blob/main/src/Functions/ioapp.php"
click node_console_functions "https://github.com/phunkie/effect/blob/main/src/Functions/console.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_io,node_io_constructor,node_resource,node_exit_case toneBlue
class node_functor_ops,node_applicative_ops,node_monad_ops,node_error_ops,node_parallel_ops,node_parallel_type toneAmber
class node_concurrent_ops,node_blocker,node_execution_context,node_fiber_context,node_parallel_context,node_async_handle,node_cancellable_handle,node_timeout_exception toneMint
class node_ioapp,node_options,node_option_definition,node_option_format,node_parsed_options,node_app_error,node_app_functions,node_console_functions toneRose
class node_developer toneIndigo
```

## Components

### IO Effects

- [Lazy IO](https://github.com/phunkie/effect/blob/main/src/IO/IO.php): `src/IO/IO.php`
- [IO Constructors](https://github.com/phunkie/effect/blob/main/src/Functions/io.php): `src/Functions/io.php`
- [Resource Safety](https://github.com/phunkie/effect/blob/main/src/IO/Resource.php): `src/IO/Resource.php`
- [Exit Cases](https://github.com/phunkie/effect/blob/main/src/IO/ExitCase.php): `src/IO/ExitCase.php`

### Composition Ops

- [Functor Ops](https://github.com/phunkie/effect/blob/main/src/Ops/IO/FunctorOps.php): `src/Ops/IO/FunctorOps.php`
- [Applicative Ops](https://github.com/phunkie/effect/blob/main/src/Ops/IO/ApplicativeOps.php): `src/Ops/IO/ApplicativeOps.php`
- [Monad Ops](https://github.com/phunkie/effect/blob/main/src/Ops/IO/MonadOps.php): `src/Ops/IO/MonadOps.php`
- [Error Recovery](https://github.com/phunkie/effect/blob/main/src/Ops/IO/MonadErrorOps.php): `src/Ops/IO/MonadErrorOps.php`
- [Parallel Ops](https://github.com/phunkie/effect/blob/main/src/Ops/IO/ParallelOps.php): `src/Ops/IO/ParallelOps.php`
- [Parallel Contract](https://github.com/phunkie/effect/blob/main/src/Cats/Parallel.php): `src/Cats/Parallel.php`

### Concurrency

- [Race And Timeout](https://github.com/phunkie/effect/blob/main/src/Ops/IO/ConcurrentOps.php): `src/Ops/IO/ConcurrentOps.php`
- [Blocking Work](https://github.com/phunkie/effect/blob/main/src/Concurrent/Blocker.php): `src/Concurrent/Blocker.php`
- [Execution Context](https://github.com/phunkie/effect/blob/main/src/Concurrent/ExecutionContext.php): `src/Concurrent/ExecutionContext.php`
- [Fiber Context](https://github.com/phunkie/effect/blob/main/src/Concurrent/FiberExecutionContext.php): `src/Concurrent/FiberExecutionContext.php`
- [Thread Context](https://github.com/phunkie/effect/blob/main/src/Concurrent/ParallelExecutionContext.php): `src/Concurrent/ParallelExecutionContext.php`
- [Async Handle](https://github.com/phunkie/effect/blob/main/src/Concurrent/AsyncHandle.php): `src/Concurrent/AsyncHandle.php`
- [Cancellable Handle](https://github.com/phunkie/effect/blob/main/src/Concurrent/CancellableHandle.php): `src/Concurrent/CancellableHandle.php`
- [Timeout Error](https://github.com/phunkie/effect/blob/main/src/Concurrent/TimeoutException.php): `src/Concurrent/TimeoutException.php`

### Application Runtime

- [IO App Entry](https://github.com/phunkie/effect/blob/main/src/IO/IOApp.php): `src/IO/IOApp.php`
- [Option Parser](https://github.com/phunkie/effect/blob/main/src/IO/IOApp/Options.php): `src/IO/IOApp/Options.php`
- [Option Definitions](https://github.com/phunkie/effect/blob/main/src/IO/IOApp/OptionDefinition.php): `src/IO/IOApp/OptionDefinition.php`
- [Option Formats](https://github.com/phunkie/effect/blob/main/src/IO/IOApp/OptionFormat.php): `src/IO/IOApp/OptionFormat.php`
- [Parsed Options](https://github.com/phunkie/effect/blob/main/src/IO/IOApp/ParsedOptions.php): `src/IO/IOApp/ParsedOptions.php`
- [CLI Errors](https://github.com/phunkie/effect/blob/main/src/IO/IOApp/Error.php): `src/IO/IOApp/Error.php`
- [CLI Builders](https://github.com/phunkie/effect/blob/main/src/Functions/ioapp.php): `src/Functions/ioapp.php`
- [Console Effects](https://github.com/phunkie/effect/blob/main/src/Functions/console.php): `src/Functions/console.php`

### Other components

- **Application Code**

## Connections

- Application Code → IO Constructors: constructs effects (evidence: `README.md`)
- IO Constructors → Lazy IO: creates IO (evidence: `src/Functions/io.php`)
- Application Code → IO App Entry: defines app (evidence: `src/IO/IOApp.php`)
- IO App Entry → Option Parser: parses arguments (evidence: `src/IO/IOApp.php`)
- Option Parser → Option Definitions: uses definitions (evidence: `src/IO/IOApp/Options.php`)
- Option Parser → Option Formats: checks formats (evidence: `src/IO/IOApp/Options.php`)
- Option Parser → Parsed Options: produces options (evidence: `src/IO/IOApp/Options.php`)
- Option Parser → CLI Errors: returns parse errors (evidence: `src/IO/IOApp/Options.php`)
- CLI Builders → Option Parser: builds definitions (evidence: `src/Functions/ioapp.php`)
- Lazy IO → Functor Ops: uses operations (evidence: `src/IO/IO.php`)
- Lazy IO → Applicative Ops: uses operations (evidence: `src/IO/IO.php`)
- Lazy IO → Monad Ops: uses operations (evidence: `src/IO/IO.php`)
- Lazy IO → Error Recovery: uses operations (evidence: `src/IO/IO.php`)
- Lazy IO → Parallel Ops: uses operations (evidence: `src/IO/IO.php`)
- Lazy IO → Race And Timeout: uses operations (evidence: `src/IO/IO.php`)
- Lazy IO → Fiber Context: defaults to (evidence: `src/IO/IO.php`)
- Lazy IO → Execution Context: accepts context (evidence: `src/IO/IO.php`)
- Parallel Ops → Thread Context: requires context (evidence: `src/Ops/IO/ParallelOps.php`)
- Parallel Ops → Blocking Work: runs blockers (evidence: `src/Ops/IO/ParallelOps.php`)
- Parallel Ops → Parallel Contract: combines values (evidence: `src/Ops/IO/ParallelOps.php`)
- Race And Timeout → Blocking Work: dispatches blocking (evidence: `src/Ops/IO/ConcurrentOps.php`)
- Race And Timeout → Execution Context: dispatches effects (evidence: `src/Ops/IO/ConcurrentOps.php`)
- Race And Timeout → Cancellable Handle: polls and cancels (evidence: `src/Ops/IO/ConcurrentOps.php`)
- Race And Timeout → Timeout Error: raises timeout (evidence: `src/Ops/IO/ConcurrentOps.php`)
- Blocking Work → Execution Context: delegates execution (evidence: `src/Concurrent/Blocker.php`)
- Execution Context → Async Handle: returns handle (evidence: `src/Concurrent/ExecutionContext.php`)
- Fiber Context → Execution Context: implements context (evidence: `src/Concurrent/FiberExecutionContext.php`)
- Fiber Context → Async Handle: returns handle (evidence: `src/Concurrent/FiberExecutionContext.php`)
- Thread Context → Execution Context: implements context (evidence: `src/Concurrent/ParallelExecutionContext.php`)
- Thread Context → Cancellable Handle: returns handle (evidence: `src/Concurrent/ParallelExecutionContext.php`)
- Thread Context → Async Handle: returns handle (evidence: `src/Concurrent/ParallelExecutionContext.php`)
- IO App Entry → Lazy IO: returns program (evidence: `src/IO/IOApp.php`)
- IO App Entry → Console Effects: writes output
- Lazy IO → Resource Safety: supports resource safety (evidence: `README.md`)
- Application Code → Parallel Ops: combines in parallel (evidence: `README.md`)