# nbun/efci architecture

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

- Interactive diagram: https://gitdiagram.com/nbun/efci
- Repository: https://github.com/nbun/efci

## Overview

1. This is a Haskell-based Curry interpreter. The repository is split into a small executable front end, an interpreter/runtime core, a transformation layer, and a set of effect handlers that model Curry semantics such as nondeterminism, state, reader context, memoization, error handling, and IO.

2. The executable entry point is `app/Main.hs`, which wires the CLI/REPL behavior to the interpreter code in `src/`. `src/App.hs` is the top-level application orchestration module, while the user-facing commands described in the README (`:q`, `:o`, `:time`, `:fcy`) indicate an interactive interpreter loop rather than a batch compiler.

3. Source programs are Curry files (`.curry`). The repository includes a `curry-frontend` submodule, which is the external frontend used to parse/translate Curry source into FlatCurry, the intermediate representation used by this interpreter. The bundled `data/Prelude.curry` and `benchmarks/data/Prelude.curry` show that Prelude loading is part of the normal runtime setup.

4. The core execution pipeline appears to be: Curry source or interactive input → frontend-generated FlatCurry → internal transformation/intermediate forms → effectful evaluation. `src/Pipeline.hs` is the obvious coordination point for these stages, and `src/Transformation/FCY2AE.hs` suggests a translation from FlatCurry into an algebraic-effects-based representation.

5. The interpreter itself is split across multiple execution styles or evaluation layers. `src/InterpFL.hs` suggests a FlatCurry interpreter, while `src/Monolith.hs` implies an alternative “all-in-one” interpreter path. The README’s “rotate between interpretation modes” strongly suggests the CLI can switch among these modes at runtime.

6. Effects are the main architectural boundary. Under `src/Effect/General/` are reusable effect handlers for `Error`, `Memoization`, `ND` (nondeterminism), `Reader`, and `State`. Under `src/Effect/FlatCurry/` are handlers specialized to FlatCurry constructs such as constructors, declarations, functions, let-bindings, and IO. This indicates the interpreter is structured as a stack of effect handlers rather than a single monolithic evaluator.

7. The effect infrastructure is supported by generic runtime machinery in `src/Free.hs`, `src/DelCont.hs`, and `src/Data/Union.hs`. These modules likely implement the underlying free/effect representation, delimited continuations, and type-safe effect unions used by the handlers. `src/Signature.hs` and `src/Type.hs` appear to define the typed interface for operations and Curry/FlatCurry types.

8. `src/Debug.hs` is a supporting diagnostics layer, likely used for tracing or development output. This is consistent with an interpreter project where visibility into evaluation order, sharing, and nondeterminism is important.

9. `examples/` contains small Curry programs used to exercise language features such as arithmetic, binary data, nondeterminism, sharing semantics, and special effects. `benchmarks/` contains larger benchmark programs plus a benchmark driver (`benchmarks/Main.hs`) and benchmark output (`benchmarks/result/bench.csv`), showing that performance and semantics across different evaluation strategies are both first-class concerns.

10. `tests/Main.hs` provides the test entry point, while `stack.yaml`, `effective-curry-interpreter.cabal`, and `fourmolu.yaml` show the project is built and formatted as a standard Haskell package. The README’s note about “not all external functions are implemented” implies there is a runtime boundary between the interpreted Curry core and host-provided primitives.

11. A useful architecture diagram would show three external inputs feeding the system: interactive user expressions, Curry source modules, and benchmark/example programs. Those all flow into the frontend/FlatCurry layer, then into the effect-based interpreter, and finally back to the REPL/benchmark/test harness as evaluated results, nondeterministic outcomes, or runtime errors.

Main entry points: [`src/Effect/General`](https://github.com/nbun/efci/tree/main/src/Effect/General) (General effects), [`src/Pipeline.hs`](https://github.com/nbun/efci/blob/main/src/Pipeline.hs) (Pipeline), [`src/Effect/FlatCurry`](https://github.com/nbun/efci/tree/main/src/Effect/FlatCurry) (FlatCurry effects), [`src/App.hs`](https://github.com/nbun/efci/blob/main/src/App.hs) (App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Front end"]
  node_node_app_main["Main<br/>CLI entrypoint<br/>[Main.hs]"]
  node_node_app["App<br/>orchestration<br/>[App.hs]"]
  node_node_tests["Tests<br/>test harness<br/>[Main.hs]"]
end

subgraph group_group_pipeline["Core pipeline"]
  node_node_pipeline["Pipeline<br/>coordination<br/>[Pipeline.hs]"]
  node_node_fcy2ae["FCY2AE<br/>translation<br/>[FCY2AE.hs]"]
  node_node_interpfl["InterpFL<br/>FlatCurry interpreter<br/>[InterpFL.hs]"]
  node_node_monolith["Monolith<br/>alternate evaluator<br/>[Monolith.hs]"]
  node_node_frontend["Frontend<br/>external submodule"]
end

subgraph group_group_effects["Effect runtime"]
  node_node_effect_general["General effects<br/>effect handlers"]
  node_node_nd(("ND<br/>[ND.hs]"))
  node_node_state(("State<br/>[State.hs]"))
  node_node_reader(("Reader<br/>context<br/>[Reader.hs]"))
  node_node_error(("Error<br/>failure<br/>[Error.hs]"))
  node_node_memo(("Memoization<br/>sharing<br/>[Memoization.hs]"))
  node_node_effect_flat["FlatCurry effects<br/>language handlers"]
  node_node_fc_ctor(("Constructors<br/>handler<br/>[Constructor.hs]"))
  node_node_fc_decl(("Declarations<br/>handler<br/>[Declarations.hs]"))
  node_node_fc_func(("Functions<br/>handler<br/>[Function.hs]"))
  node_node_fc_let(("Let<br/>handler<br/>[Let.hs]"))
  node_node_fc_io(("IO<br/>[IO.hs]"))
end

subgraph group_group_support["Support"]
  node_node_free["Free<br/>effect core<br/>[Free.hs]"]
  node_node_delcont["DelCont<br/>continuations<br/>[DelCont.hs]"]
  node_node_union["Union<br/>[Union.hs]"]
  node_node_signature["Signature<br/>operations<br/>[Signature.hs]"]
  node_node_type["Type<br/>[Type.hs]"]
  node_node_debug["Debug<br/>tracing<br/>[Debug.hs]"]
end

subgraph group_group_content["Inputs and workloads"]
  node_node_prelude["Prelude<br/>runtime data<br/>[Prelude.curry]"]
  node_node_examples["Examples<br/>Curry programs"]
  node_node_benchmarks["Benchmarks"]
end

node_node_app_main -->|"starts"| node_node_app
node_node_app -->|"drives"| node_node_pipeline
node_node_pipeline -->|"parses"| node_node_frontend
node_node_pipeline -->|"transforms"| node_node_fcy2ae
node_node_pipeline -->|"evaluates"| node_node_interpfl
node_node_pipeline -->|"evaluates"| node_node_monolith
node_node_pipeline -->|"loads"| node_node_prelude
node_node_interpfl -->|"uses"| node_node_effect_flat
node_node_monolith -->|"uses"| node_node_effect_general
node_node_fcy2ae -->|"targets"| node_node_effect_general
node_node_effect_flat -->|"includes"| node_node_fc_ctor
node_node_effect_flat -->|"includes"| node_node_fc_decl
node_node_effect_flat -->|"includes"| node_node_fc_func
node_node_effect_flat -->|"includes"| node_node_fc_let
node_node_effect_flat -->|"includes"| node_node_fc_io
node_node_effect_general -->|"contains"| node_node_nd
node_node_effect_general -->|"contains"| node_node_state
node_node_effect_general -->|"contains"| node_node_reader
node_node_effect_general -->|"contains"| node_node_error
node_node_effect_general -->|"contains"| node_node_memo
node_node_effect_general -->|"built on"| node_node_free
node_node_effect_general -->|"built on"| node_node_delcont
node_node_effect_general -->|"built on"| node_node_union
node_node_effect_general -->|"uses"| node_node_signature
node_node_effect_general -->|"uses"| node_node_type
node_node_app -.->|"traces"| node_node_debug
node_node_tests -->|"exercises"| node_node_pipeline
node_node_benchmarks -->|"measures"| node_node_pipeline
node_node_examples -->|"feeds"| node_node_frontend
node_node_benchmarks -->|"depends on"| node_node_prelude
node_node_fc_io -->|"reports"| node_node_error

click node_node_app_main "https://github.com/nbun/efci/blob/main/app/Main.hs"
click node_node_app "https://github.com/nbun/efci/blob/main/src/App.hs"
click node_node_pipeline "https://github.com/nbun/efci/blob/main/src/Pipeline.hs"
click node_node_fcy2ae "https://github.com/nbun/efci/blob/main/src/Transformation/FCY2AE.hs"
click node_node_interpfl "https://github.com/nbun/efci/blob/main/src/InterpFL.hs"
click node_node_monolith "https://github.com/nbun/efci/blob/main/src/Monolith.hs"
click node_node_effect_general "https://github.com/nbun/efci/tree/main/src/Effect/General"
click node_node_nd "https://github.com/nbun/efci/blob/main/src/Effect/General/ND.hs"
click node_node_state "https://github.com/nbun/efci/blob/main/src/Effect/General/State.hs"
click node_node_reader "https://github.com/nbun/efci/blob/main/src/Effect/General/Reader.hs"
click node_node_error "https://github.com/nbun/efci/blob/main/src/Effect/General/Error.hs"
click node_node_memo "https://github.com/nbun/efci/blob/main/src/Effect/General/Memoization.hs"
click node_node_effect_flat "https://github.com/nbun/efci/tree/main/src/Effect/FlatCurry"
click node_node_fc_ctor "https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/Constructor.hs"
click node_node_fc_decl "https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/Declarations.hs"
click node_node_fc_func "https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/Function.hs"
click node_node_fc_let "https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/Let.hs"
click node_node_fc_io "https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/IO.hs"
click node_node_free "https://github.com/nbun/efci/blob/main/src/Free.hs"
click node_node_delcont "https://github.com/nbun/efci/blob/main/src/DelCont.hs"
click node_node_union "https://github.com/nbun/efci/blob/main/src/Data/Union.hs"
click node_node_signature "https://github.com/nbun/efci/blob/main/src/Signature.hs"
click node_node_type "https://github.com/nbun/efci/blob/main/src/Type.hs"
click node_node_debug "https://github.com/nbun/efci/blob/main/src/Debug.hs"
click node_node_prelude "https://github.com/nbun/efci/blob/main/data/Prelude.curry"
click node_node_examples "https://github.com/nbun/efci/tree/main/examples"
click node_node_benchmarks "https://github.com/nbun/efci/tree/main/benchmarks"
click node_node_tests "https://github.com/nbun/efci/blob/main/tests/Main.hs"
click node_node_frontend "https://github.com/nbun/efci/tree/main/curry-frontend"

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_node_app_main,node_node_app,node_node_tests toneBlue
class node_node_pipeline,node_node_fcy2ae,node_node_interpfl,node_node_monolith,node_node_frontend toneAmber
class node_node_effect_general,node_node_nd,node_node_state,node_node_reader,node_node_error,node_node_memo,node_node_effect_flat,node_node_fc_ctor,node_node_fc_decl,node_node_fc_func,node_node_fc_let,node_node_fc_io toneMint
class node_node_free,node_node_delcont,node_node_union,node_node_signature,node_node_type,node_node_debug toneRose
class node_node_prelude,node_node_examples,node_node_benchmarks toneIndigo
```

## Components

### Front end

User entrypoints and project-facing orchestration.

- [Main](https://github.com/nbun/efci/blob/main/app/Main.hs): CLI entrypoint · Executable entry point that starts the interpreter or REPL. · `app/Main.hs`
- [App](https://github.com/nbun/efci/blob/main/src/App.hs): orchestration · Top-level application wiring and command handling. · `src/App.hs`
- [Tests](https://github.com/nbun/efci/blob/main/tests/Main.hs): test harness · Test entrypoint for the Haskell package. · `tests/Main.hs`

### Core pipeline

Translation and interpreter coordination.

- [Pipeline](https://github.com/nbun/efci/blob/main/src/Pipeline.hs): coordination · Coordinates source loading, translation, and execution stages. · `src/Pipeline.hs`
- [FCY2AE](https://github.com/nbun/efci/blob/main/src/Transformation/FCY2AE.hs): translation · Transforms FlatCurry into an algebraic-effects representation. · `src/Transformation/FCY2AE.hs`
- [InterpFL](https://github.com/nbun/efci/blob/main/src/InterpFL.hs): FlatCurry interpreter · Interpreter path specialized around FlatCurry evaluation. · `src/InterpFL.hs`
- [Monolith](https://github.com/nbun/efci/blob/main/src/Monolith.hs): alternate evaluator · Alternative all-in-one evaluation path. · `src/Monolith.hs`
- [Frontend](https://github.com/nbun/efci/tree/main/curry-frontend): external submodule · External Curry frontend used to parse and produce FlatCurry. · `curry-frontend`

### Effect runtime

General effect machinery and FlatCurry-specific handlers.

- [General effects](https://github.com/nbun/efci/tree/main/src/Effect/General): effect handlers · Reusable handlers for core computational effects. · `src/Effect/General`
- [ND](https://github.com/nbun/efci/blob/main/src/Effect/General/ND.hs): nondeterminism · Branches and searches through multiple outcomes. · `src/Effect/General/ND.hs`
- [State](https://github.com/nbun/efci/blob/main/src/Effect/General/State.hs): mutable state · Threaded interpreter state. · `src/Effect/General/State.hs`
- [Reader](https://github.com/nbun/efci/blob/main/src/Effect/General/Reader.hs): context · Shared read-only execution context. · `src/Effect/General/Reader.hs`
- [Error](https://github.com/nbun/efci/blob/main/src/Effect/General/Error.hs): failure · Runtime error and exception handling. · `src/Effect/General/Error.hs`
- [Memoization](https://github.com/nbun/efci/blob/main/src/Effect/General/Memoization.hs): sharing · Caches results to preserve sharing semantics. · `src/Effect/General/Memoization.hs`
- [FlatCurry effects](https://github.com/nbun/efci/tree/main/src/Effect/FlatCurry): language handlers · Handlers specialized to FlatCurry constructs. · `src/Effect/FlatCurry`
- [Constructors](https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/Constructor.hs): handler · Handles data constructor evaluation. · `src/Effect/FlatCurry/Constructor.hs`
- [Declarations](https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/Declarations.hs): handler · Processes declarations and bindings. · `src/Effect/FlatCurry/Declarations.hs`
- [Functions](https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/Function.hs): handler · Evaluates function application and rules. · `src/Effect/FlatCurry/Function.hs`
- [Let](https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/Let.hs): handler · Models let-bound sharing and scope. · `src/Effect/FlatCurry/Let.hs`
- [IO](https://github.com/nbun/efci/blob/main/src/Effect/FlatCurry/IO.hs): host IO · Bridges interpreted code to host-provided IO. · `src/Effect/FlatCurry/IO.hs`

### Support

Types, debugging, and runtime plumbing.

- [Free](https://github.com/nbun/efci/blob/main/src/Free.hs): effect core · Core free/effect representation utilities. · `src/Free.hs`
- [DelCont](https://github.com/nbun/efci/blob/main/src/DelCont.hs): continuations · Delimited continuation machinery used by effects. · `src/DelCont.hs`
- [Union](https://github.com/nbun/efci/blob/main/src/Data/Union.hs): effect union · Type-safe union for composing effects. · `src/Data/Union.hs`
- [Signature](https://github.com/nbun/efci/blob/main/src/Signature.hs): operations · Typed operation signatures for effects and evaluation. · `src/Signature.hs`
- [Type](https://github.com/nbun/efci/blob/main/src/Type.hs): language types · Curry and FlatCurry type representations. · `src/Type.hs`
- [Debug](https://github.com/nbun/efci/blob/main/src/Debug.hs): tracing · Diagnostics and tracing support. · `src/Debug.hs`

### Inputs and workloads

Curry programs used by the interpreter, examples, and benchmarks.

- [Prelude](https://github.com/nbun/efci/blob/main/data/Prelude.curry): runtime data · Bundled Curry Prelude loaded at runtime. · `data/Prelude.curry`
- [Examples](https://github.com/nbun/efci/tree/main/examples): Curry programs · Small programs covering language features and semantics. · `examples`
- [Benchmarks](https://github.com/nbun/efci/tree/main/benchmarks): Curry benchmarks · Benchmark suite and results for evaluation strategies. · `benchmarks`

## Connections

- Main → App: starts · Executable delegates to application orchestration.
- App → Pipeline: drives · App wires CLI/REPL commands into the processing pipeline.
- Pipeline → Frontend: parses · Source Curry modules are translated through the external frontend.
- Pipeline → FCY2AE: transforms · FlatCurry is lowered into the effect-based internal form.
- Pipeline → InterpFL: evaluates · One execution mode runs the FlatCurry interpreter path.
- Pipeline → Monolith: evaluates · Another execution mode uses the monolithic evaluator.
- Pipeline → Prelude: loads · Prelude is part of normal runtime initialization.
- InterpFL → FlatCurry effects: uses · Interpreter evaluation is assembled from FlatCurry effect handlers.
- Monolith → General effects: uses · Monolithic path still relies on the shared effect runtime.
- FCY2AE → General effects: targets · Translation produces structures consumed by general effect handlers.
- FlatCurry effects → Constructors: includes · Constructor semantics are handled separately.
- FlatCurry effects → Declarations: includes · Declaration processing is a dedicated handler.
- FlatCurry effects → Functions: includes · Function evaluation is a dedicated handler.
- FlatCurry effects → Let: includes · Let-binding semantics and sharing are handled explicitly.
- FlatCurry effects → IO: includes · IO is bridged through a specialized handler.
- General effects → ND: contains · Nondeterminism is one of the core general effects.
- General effects → State: contains · State is threaded through execution via effects.
- General effects → Reader: contains · Read-only interpreter context is provided by Reader.
- General effects → Error: contains · Runtime failures are represented as an effect.
- General effects → Memoization: contains · Memoization preserves sharing and avoids recomputation.
- General effects → Free: built on · Effect handlers are supported by the free-effect core.
- General effects → DelCont: built on · Delimited continuations support effect resumption.
- General effects → Union: built on · Typed unions compose the effect stack.
- General effects → Signature: uses · Operations are described through typed signatures.
- General effects → Type: uses · Evaluation and effect interfaces depend on Curry types.
- App → Debug: traces · Diagnostics support interactive debugging and evaluation visibility.
- Tests → Pipeline: exercises · Tests invoke the interpreter pipeline.
- Benchmarks → Pipeline: measures · Benchmarks compare interpretation strategies and performance.
- Examples → Frontend: feeds · Example Curry programs are parsed through the frontend.
- Benchmarks → Prelude: depends on · Benchmark programs also rely on the bundled Prelude.
- IO → Error: reports · IO boundaries can surface runtime errors.