# bencagri/amel architecture

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

- Interactive diagram: https://gitdiagram.com/bencagri/amel
- Repository: https://github.com/bencagri/amel

## Overview

AMEL is a typed DSL for evaluating expressions against JSON payloads and compiling expressions to SQL or MongoDB queries. The primary workflow is expression text through lexing, parsing, optional optimization, and evaluation against a payload; function calls extend evaluation with built-ins or sandboxed JavaScript. Compilation is a separate path from an AST to a target query. README capabilities include JSONPath access, regex, lambdas and array operations, and explainable evaluation. The graph follows shown calls and documented capabilities; unsampled implementation details are not inferred.

Main entry points: [`pkg/engine/engine.go`](https://github.com/bencagri/amel/blob/main/pkg/engine/engine.go) (Engine API), [`pkg/eval/evaluator.go`](https://github.com/bencagri/amel/blob/main/pkg/eval/evaluator.go) (Evaluator), [`pkg/ast/ast.go`](https://github.com/bencagri/amel/blob/main/pkg/ast/ast.go) (Expression AST), [`pkg/parser/parser.go`](https://github.com/bencagri/amel/blob/main/pkg/parser/parser.go) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["DSL Front End"]
  node_lexer["Lexer<br/>[lexer.go]"]
  node_tokens["Token Types<br/>[token.go]"]
  node_parser["Parser<br/>[parser.go]"]
  node_ast["Expression AST<br/>[ast.go]"]
  node_optimizer["AST Optimizer<br/>[optimizer.go]"]
end

subgraph group_runtime["Evaluation Runtime"]
  node_engine["Engine API<br/>[engine.go]"]
  node_evaluator["Evaluator<br/>[evaluator.go]"]
  node_values["Typed Values<br/>[types.go]"]
end

subgraph group_functions["Function System"]
  node_functions_registry["Function Registry<br/>[registry.go]"]
  node_builtins["Built-ins<br/>[builtin.go]"]
  node_sandbox["JS Sandbox<br/>[sandbox.go]"]
end

subgraph group_targets["Query Compilation"]
  node_sql["SQL Compiler<br/>[sql.go]"]
  node_mongodb["MongoDB Compiler<br/>[mongodb.go]"]
end

node_user(("Application"))
node_payload["JSON Payload"]
node_result["Evaluation Result"]

node_user -->|"submits expression"| node_engine
node_engine -->|"parses expression"| node_parser
node_parser -->|"creates lexer"| node_lexer
node_lexer -.->|"produces tokens"| node_tokens
node_parser -->|"builds AST"| node_ast
node_engine -->|"optimizes AST"| node_optimizer
node_engine -->|"evaluates AST"| node_evaluator
node_engine -->|"retains source AST"| node_ast
node_payload -->|"supplies data"| node_engine
node_evaluator -->|"creates typed values"| node_values
node_evaluator -->|"dispatches calls"| node_functions_registry
node_functions_registry -->|"registers built-ins"| node_builtins
node_evaluator -->|"invokes JS"| node_sandbox
node_engine -->|"registers functions"| node_functions_registry
node_evaluator -->|"returns value"| node_result
node_user -->|"requests SQL compilation"| node_sql
node_user -->|"requests MongoDB compilation"| node_mongodb
node_sql -->|"compiles expression"| node_ast
node_mongodb -->|"compiles expression"| node_ast

click node_engine "https://github.com/bencagri/amel/blob/main/pkg/engine/engine.go"
click node_lexer "https://github.com/bencagri/amel/blob/main/pkg/lexer/lexer.go"
click node_tokens "https://github.com/bencagri/amel/blob/main/pkg/lexer/token.go"
click node_parser "https://github.com/bencagri/amel/blob/main/pkg/parser/parser.go"
click node_ast "https://github.com/bencagri/amel/blob/main/pkg/ast/ast.go"
click node_optimizer "https://github.com/bencagri/amel/blob/main/pkg/optimizer/optimizer.go"
click node_evaluator "https://github.com/bencagri/amel/blob/main/pkg/eval/evaluator.go"
click node_values "https://github.com/bencagri/amel/blob/main/pkg/types/types.go"
click node_functions_registry "https://github.com/bencagri/amel/blob/main/pkg/functions/registry.go"
click node_builtins "https://github.com/bencagri/amel/blob/main/pkg/functions/builtin.go"
click node_sandbox "https://github.com/bencagri/amel/blob/main/pkg/functions/sandbox.go"
click node_sql "https://github.com/bencagri/amel/blob/main/pkg/compiler/sql.go"
click node_mongodb "https://github.com/bencagri/amel/blob/main/pkg/compiler/mongodb.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_lexer,node_tokens,node_parser,node_ast,node_optimizer toneBlue
class node_engine,node_evaluator,node_values toneAmber
class node_functions_registry,node_builtins,node_sandbox toneMint
class node_sql,node_mongodb toneRose
class node_user,node_payload,node_result toneIndigo
```

## Components

### DSL Front End

- [Lexer](https://github.com/bencagri/amel/blob/main/pkg/lexer/lexer.go): `pkg/lexer/lexer.go`
- [Token Types](https://github.com/bencagri/amel/blob/main/pkg/lexer/token.go): `pkg/lexer/token.go`
- [Parser](https://github.com/bencagri/amel/blob/main/pkg/parser/parser.go): `pkg/parser/parser.go`
- [Expression AST](https://github.com/bencagri/amel/blob/main/pkg/ast/ast.go): `pkg/ast/ast.go`
- [AST Optimizer](https://github.com/bencagri/amel/blob/main/pkg/optimizer/optimizer.go): `pkg/optimizer/optimizer.go`

### Evaluation Runtime

- [Engine API](https://github.com/bencagri/amel/blob/main/pkg/engine/engine.go): `pkg/engine/engine.go`
- [Evaluator](https://github.com/bencagri/amel/blob/main/pkg/eval/evaluator.go): `pkg/eval/evaluator.go`
- [Typed Values](https://github.com/bencagri/amel/blob/main/pkg/types/types.go): `pkg/types/types.go`

### Function System

- [Function Registry](https://github.com/bencagri/amel/blob/main/pkg/functions/registry.go): `pkg/functions/registry.go`
- [Built-ins](https://github.com/bencagri/amel/blob/main/pkg/functions/builtin.go): `pkg/functions/builtin.go`
- [JS Sandbox](https://github.com/bencagri/amel/blob/main/pkg/functions/sandbox.go): `pkg/functions/sandbox.go`

### Query Compilation

- [SQL Compiler](https://github.com/bencagri/amel/blob/main/pkg/compiler/sql.go): `pkg/compiler/sql.go`
- [MongoDB Compiler](https://github.com/bencagri/amel/blob/main/pkg/compiler/mongodb.go): `pkg/compiler/mongodb.go`

### Other components

- **Application**
- **JSON Payload**
- **Evaluation Result**

## Connections

- Application → Engine API: submits expression (evidence: `README.md`)
- Engine API → Parser: parses expression (evidence: `pkg/engine/engine.go`)
- Parser → Lexer: creates lexer (evidence: `pkg/parser/parser.go`)
- Lexer → Token Types: produces tokens
- Parser → Expression AST: builds AST (evidence: `pkg/parser/parser.go`)
- Engine API → AST Optimizer: optimizes AST (evidence: `pkg/engine/engine.go`)
- Engine API → Evaluator: evaluates AST (evidence: `pkg/engine/engine.go`)
- Engine API → Expression AST: retains source AST (evidence: `pkg/engine/engine.go`)
- JSON Payload → Engine API: supplies data (evidence: `README.md`)
- Evaluator → Typed Values: creates typed values (evidence: `pkg/eval/evaluator.go`)
- Evaluator → Function Registry: dispatches calls (evidence: `pkg/eval/evaluator.go`)
- Function Registry → Built-ins: registers built-ins (evidence: `pkg/functions/builtin.go`)
- Evaluator → JS Sandbox: invokes JS (evidence: `pkg/eval/evaluator.go`)
- Engine API → Function Registry: registers functions (evidence: `pkg/engine/engine.go`)
- Evaluator → Evaluation Result: returns value (evidence: `README.md`)
- Application → SQL Compiler: requests SQL compilation (evidence: `README.md`)
- Application → MongoDB Compiler: requests MongoDB compilation (evidence: `README.md`)
- SQL Compiler → Expression AST: compiles expression (evidence: `pkg/compiler/sql.go`)
- MongoDB Compiler → Expression AST: compiles expression (evidence: `pkg/compiler/mongodb.go`)
