# montferret/ferret architecture

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

- Interactive diagram: https://gitdiagram.com/montferret/ferret
- Repository: https://github.com/montferret/ferret

## Overview

Ferret is an embeddable Go runtime for the FQL declarative language. Its documented primary workflow is to configure an engine, compile a query into a reusable plan, create an isolated session, run it, and collect or consume the encoded output. The map also preserves querying, host extension, portable bytecode, debugging, compatibility, and source-formatting capabilities. Relationships are limited to the README workflow and source-index or excerpt evidence; several subsystem internals were not sampled.

Main entry points: [`engine_options.go`](https://github.com/montferret/ferret/blob/main/engine_options.go) (Engine options), [`pkg/engine/engine.go`](https://github.com/montferret/ferret/blob/main/pkg/engine/engine.go) (Engine), [`pkg/compiler`](https://github.com/montferret/ferret/tree/main/pkg/compiler) (Compiler), [`pkg/engine/plan_session.go`](https://github.com/montferret/ferret/blob/main/pkg/engine/plan_session.go) (Plans and sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language and compilation"]
  node_compiler["Compiler"]
  node_query_compiler["Query expressions"]
  node_parser["FQL parser<br/>[parser.go]"]
  node_diagnostics["Parse diagnostics"]
  node_optimizer["Optimization passes<br/>[pipeline.go]"]
  node_bytecode["Bytecode program<br/>[program.go]"]
  node_artifacts["Program artifacts"]
end

subgraph group_execution["Runtime and execution"]
  node_plan_session["Plans and sessions<br/>[plan_session.go]"]
  node_vm["Bytecode VM"]
  node_runtime["Value runtime"]
  node_query["Queryable values<br/>[queryable.go]"]
  node_stdlib["Standard library<br/>[lib.go]"]
  node_resources["Resource lifecycle<br/>[manager.go]"]
  node_encoding["Encoding and output<br/>[output.go]"]
end

subgraph group_embedding["Embedding and extensions"]
  node_engine_api["Native API<br/>[engine.go]"]
  node_engine["Engine<br/>[engine.go]"]
  node_engine_config["Engine options<br/>[engine_options.go]"]
  node_modules["Modules and hooks"]
  node_sdk["Host-value SDK<br/>[decode.go]"]
end

subgraph group_interfaces["Developer interfaces"]
  node_debugger["Debugger sessions<br/>[session.go]"]
  node_formatter["FQL formatter<br/>[engine.go]"]
  node_compat["Compatibility API<br/>[compat.go]"]
  node_uapi["Universal adapter<br/>[debug_session.go]"]
end

node_developer(("Host application"))

node_developer -->|"embeds"| node_engine_api
node_engine_api -->|"constructs"| node_engine
node_developer -->|"configures"| node_engine_config
node_engine_config -->|"sets options"| node_engine
node_engine -->|"compiles with"| node_compiler
node_compiler -->|"emits"| node_bytecode
node_compiler -->|"uses grammar"| node_parser
node_compiler -.->|"optimizes"| node_optimizer
node_optimizer -->|"rewrites"| node_bytecode
node_engine -->|"creates plan"| node_plan_session
node_plan_session -.->|"executes"| node_vm
node_vm -->|"evaluates values"| node_runtime
node_vm -->|"dispatches queries"| node_query
node_query -->|"uses values"| node_runtime
node_engine_config -->|"registers modules"| node_modules
node_engine_config -->|"selects libraries"| node_stdlib
node_engine -->|"owns resources"| node_resources
node_plan_session -->|"produces output"| node_encoding
node_developer -->|"collects output"| node_encoding
node_engine_config -->|"configures loading"| node_artifacts
node_developer -->|"converts host values"| node_sdk
node_developer -->|"inspects sessions"| node_debugger
node_developer -.->|"formats source"| node_formatter
node_developer -->|"migrates integrations"| node_compat
node_developer -->|"uses adapter"| node_uapi
node_parser -->|"reports errors"| node_diagnostics

click node_engine_api "https://github.com/montferret/ferret/blob/main/engine.go"
click node_engine "https://github.com/montferret/ferret/blob/main/pkg/engine/engine.go"
click node_engine_config "https://github.com/montferret/ferret/blob/main/engine_options.go"
click node_modules "https://github.com/montferret/ferret/tree/main/pkg/module"
click node_sdk "https://github.com/montferret/ferret/blob/main/pkg/sdk/decode.go"
click node_compiler "https://github.com/montferret/ferret/tree/main/pkg/compiler"
click node_query_compiler "https://github.com/montferret/ferret/blob/main/pkg/compiler/internal/expr_query_compiler.go"
click node_parser "https://github.com/montferret/ferret/blob/main/pkg/parser/parser.go"
click node_diagnostics "https://github.com/montferret/ferret/blob/main/pkg/parser/diagnostics/match_error_query.go"
click node_optimizer "https://github.com/montferret/ferret/blob/main/pkg/compiler/internal/optimization/pipeline.go"
click node_bytecode "https://github.com/montferret/ferret/blob/main/pkg/bytecode/program.go"
click node_artifacts "https://github.com/montferret/ferret/tree/main/pkg/bytecode/artifact"
click node_plan_session "https://github.com/montferret/ferret/blob/main/pkg/engine/plan_session.go"
click node_vm "https://github.com/montferret/ferret/tree/main/pkg/vm"
click node_runtime "https://github.com/montferret/ferret/tree/main/pkg/runtime"
click node_query "https://github.com/montferret/ferret/blob/main/pkg/runtime/queryable.go"
click node_stdlib "https://github.com/montferret/ferret/blob/main/pkg/stdlib/lib.go"
click node_resources "https://github.com/montferret/ferret/blob/main/pkg/engine/internal/resource/manager.go"
click node_encoding "https://github.com/montferret/ferret/blob/main/pkg/encoding/output.go"
click node_debugger "https://github.com/montferret/ferret/blob/main/pkg/debugger/session.go"
click node_formatter "https://github.com/montferret/ferret/blob/main/pkg/formatter/internal/engine.go"
click node_compat "https://github.com/montferret/ferret/blob/main/compat/compat.go"
click node_uapi "https://github.com/montferret/ferret/blob/main/uapi/debug_session.go"

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_compiler,node_query_compiler,node_parser,node_diagnostics,node_optimizer,node_bytecode,node_artifacts toneBlue
class node_plan_session,node_vm,node_runtime,node_query,node_stdlib,node_resources,node_encoding toneAmber
class node_engine_api,node_engine,node_engine_config,node_modules,node_sdk toneMint
class node_debugger,node_formatter,node_compat,node_uapi toneRose
class node_developer toneIndigo
```

## Components

### Language and compilation

- [Compiler](https://github.com/montferret/ferret/tree/main/pkg/compiler): `pkg/compiler`
- [Query expressions](https://github.com/montferret/ferret/blob/main/pkg/compiler/internal/expr_query_compiler.go): `pkg/compiler/internal/expr_query_compiler.go`
- [FQL parser](https://github.com/montferret/ferret/blob/main/pkg/parser/parser.go): `pkg/parser/parser.go`
- [Parse diagnostics](https://github.com/montferret/ferret/blob/main/pkg/parser/diagnostics/match_error_query.go): `pkg/parser/diagnostics/match_error_query.go`
- [Optimization passes](https://github.com/montferret/ferret/blob/main/pkg/compiler/internal/optimization/pipeline.go): `pkg/compiler/internal/optimization/pipeline.go`
- [Bytecode program](https://github.com/montferret/ferret/blob/main/pkg/bytecode/program.go): `pkg/bytecode/program.go`
- [Program artifacts](https://github.com/montferret/ferret/tree/main/pkg/bytecode/artifact): `pkg/bytecode/artifact`

### Runtime and execution

- [Plans and sessions](https://github.com/montferret/ferret/blob/main/pkg/engine/plan_session.go): `pkg/engine/plan_session.go`
- [Bytecode VM](https://github.com/montferret/ferret/tree/main/pkg/vm): `pkg/vm`
- [Value runtime](https://github.com/montferret/ferret/tree/main/pkg/runtime): `pkg/runtime`
- [Queryable values](https://github.com/montferret/ferret/blob/main/pkg/runtime/queryable.go): `pkg/runtime/queryable.go`
- [Standard library](https://github.com/montferret/ferret/blob/main/pkg/stdlib/lib.go): `pkg/stdlib/lib.go`
- [Resource lifecycle](https://github.com/montferret/ferret/blob/main/pkg/engine/internal/resource/manager.go): `pkg/engine/internal/resource/manager.go`
- [Encoding and output](https://github.com/montferret/ferret/blob/main/pkg/encoding/output.go): `pkg/encoding/output.go`

### Embedding and extensions

- [Native API](https://github.com/montferret/ferret/blob/main/engine.go): `engine.go`
- [Engine](https://github.com/montferret/ferret/blob/main/pkg/engine/engine.go): `pkg/engine/engine.go`
- [Engine options](https://github.com/montferret/ferret/blob/main/engine_options.go): `engine_options.go`
- [Modules and hooks](https://github.com/montferret/ferret/tree/main/pkg/module): `pkg/module`
- [Host-value SDK](https://github.com/montferret/ferret/blob/main/pkg/sdk/decode.go): `pkg/sdk/decode.go`

### Developer interfaces

- [Debugger sessions](https://github.com/montferret/ferret/blob/main/pkg/debugger/session.go): `pkg/debugger/session.go`
- [FQL formatter](https://github.com/montferret/ferret/blob/main/pkg/formatter/internal/engine.go): `pkg/formatter/internal/engine.go`
- [Compatibility API](https://github.com/montferret/ferret/blob/main/compat/compat.go): `compat/compat.go`
- [Universal adapter](https://github.com/montferret/ferret/blob/main/uapi/debug_session.go): `uapi/debug_session.go`

### Other components

- **Host application**

## Connections

- Host application → Native API: embeds
- Native API → Engine: constructs (evidence: `engine.go`)
- Host application → Engine options: configures (evidence: `engine_options.go`)
- Engine options → Engine: sets options (evidence: `engine_options.go`)
- Engine → Compiler: compiles with (evidence: `pkg/engine/engine.go`)
- Compiler → Bytecode program: emits (evidence: `pkg/compiler/internal/expr_query_compiler.go`)
- Compiler → FQL parser: uses grammar (evidence: `pkg/compiler/internal/expr_query_compiler.go`)
- Compiler → Optimization passes: optimizes
- Optimization passes → Bytecode program: rewrites (evidence: `pkg/compiler/internal/optimization/pipeline.go`)
- Engine → Plans and sessions: creates plan
- Plans and sessions → Bytecode VM: executes
- Bytecode VM → Value runtime: evaluates values (evidence: `pkg/vm/query.go`)
- Bytecode VM → Queryable values: dispatches queries (evidence: `pkg/vm/query.go`)
- Queryable values → Value runtime: uses values
- Engine options → Modules and hooks: registers modules
- Engine options → Standard library: selects libraries (evidence: `engine_options.go`)
- Engine → Resource lifecycle: owns resources (evidence: `pkg/engine/engine.go`)
- Plans and sessions → Encoding and output: produces output
- Host application → Encoding and output: collects output
- Engine options → Program artifacts: configures loading (evidence: `engine_options.go`)
- Host application → Host-value SDK: converts host values
- Host application → Debugger sessions: inspects sessions (evidence: `pkg/debugger/session.go`)
- Host application → FQL formatter: formats source
- Host application → Compatibility API: migrates integrations
- Host application → Universal adapter: uses adapter
- FQL parser → Parse diagnostics: reports errors (evidence: `pkg/parser/diagnostics/match_error_query.go`)