# salesforce/formula-engine architecture

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

- Interactive diagram: https://gitdiagram.com/salesforce/formula-engine
- Repository: https://github.com/salesforce/formula-engine

## Overview

formula-engine is a reusable, Salesforce-syntax formula library with Java evaluation and JavaScript/SQL generation. The principal workflow is to configure hooks, types and a data context; compile a formula through the factory; then evaluate the compiled formula with a runtime context. Compiled formula information can be reused with different runtime contexts. The README also documents template support and client/offline JavaScript use. Relationships below follow README statements; unsampled implementation details are not inferred.

Main entry points: [`impl/src/main/java/com/force/formula/impl/FormulaImpl.java`](https://github.com/salesforce/formula-engine/blob/main/impl/src/main/java/com/force/formula/impl/FormulaImpl.java) (Compiled formula), [`impl/src/main/java/com/force/formula/impl/FormulaFactoryImpl.java`](https://github.com/salesforce/formula-engine/blob/main/impl/src/main/java/com/force/formula/impl/FormulaFactoryImpl.java) (Formula factory), [`api/src/main/java/com/force/formula/FormulaContext.java`](https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaContext.java) (Data context), [`api/src/main/java/com/force/formula/sql/FormulaSQLProvider.java`](https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/sql/FormulaSQLProvider.java) (SQL generation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Application integration"]
  node_hooks["Engine hooks"]
  node_typeconfig["Formula type config"]
  node_datatype["Data types"]
end

subgraph group_formula["Formula compilation"]
  node_factory["Formula factory"]
  node_parser["Formula parser"]
  node_commands["Formula commands"]
  node_compiled["Compiled formula<br/>[FormulaImpl.java]"]
  node_templates["Template functions"]
end

subgraph group_execution["Evaluation and contexts"]
  node_context["Data context"]
  node_runtime["Runtime context"]
  node_schema["Schema metadata<br/>[FormulaSchema.java]"]
end

subgraph group_generation["Output generation"]
  node_sqlapi["SQL generation API"]
  node_sqlhooks["SQL dialect hooks"]
  node_javascript["JavaScript runtime<br/>[formulaEngine.js]"]
end

node_application(("Application"))

node_application -->|"configures"| node_hooks
node_application -->|"implements"| node_typeconfig
node_application -->|"implements"| node_datatype
node_application -->|"provides"| node_context
node_application -->|"customizes"| node_factory
node_factory -.->|"compiles"| node_parser
node_application -->|"creates"| node_compiled
node_compiled -->|"evaluates with"| node_runtime
node_context -.->|"exposes"| node_schema
node_compiled -->|"generates SQL"| node_sqlapi
node_sqlapi -.->|"uses dialects"| node_sqlhooks
node_compiled -->|"generates JavaScript"| node_javascript
node_application -.->|"extends with"| node_templates

click node_hooks "https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaEngineHooks.java"
click node_typeconfig "https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaTypeSpec.java"
click node_datatype "https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaDataType.java"
click node_context "https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaContext.java"
click node_factory "https://github.com/salesforce/formula-engine/blob/main/impl/src/main/java/com/force/formula/impl/FormulaFactoryImpl.java"
click node_parser "https://github.com/salesforce/formula-engine/blob/main/impl/src/main/java/com/force/formula/impl/FormulaParserImpl.java"
click node_commands "https://github.com/salesforce/formula-engine/tree/main/impl/src/main/java/com/force/formula/commands"
click node_compiled "https://github.com/salesforce/formula-engine/blob/main/impl/src/main/java/com/force/formula/impl/FormulaImpl.java"
click node_runtime "https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaRuntimeContext.java"
click node_schema "https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaSchema.java"
click node_sqlapi "https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/sql/FormulaSQLProvider.java"
click node_sqlhooks "https://github.com/salesforce/formula-engine/tree/main/impl/src/main/java/com/force/formula/impl/sql"
click node_javascript "https://github.com/salesforce/formula-engine/blob/main/impl/src/main/resources/com/force/formula/formulaEngine.js"
click node_templates "https://github.com/salesforce/formula-engine/tree/main/impl/src/main/java/com/force/formula/template/commands"

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_hooks,node_typeconfig,node_datatype toneBlue
class node_factory,node_parser,node_commands,node_compiled,node_templates toneAmber
class node_context,node_runtime,node_schema toneMint
class node_sqlapi,node_sqlhooks,node_javascript toneRose
class node_application toneIndigo
```

## Components

### Application integration

- [Engine hooks](https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaEngineHooks.java): `api/src/main/java/com/force/formula/FormulaEngineHooks.java`
- [Formula type config](https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaTypeSpec.java): `api/src/main/java/com/force/formula/FormulaTypeSpec.java`
- [Data types](https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaDataType.java): `api/src/main/java/com/force/formula/FormulaDataType.java`

### Formula compilation

- [Formula factory](https://github.com/salesforce/formula-engine/blob/main/impl/src/main/java/com/force/formula/impl/FormulaFactoryImpl.java): `impl/src/main/java/com/force/formula/impl/FormulaFactoryImpl.java`
- [Formula parser](https://github.com/salesforce/formula-engine/blob/main/impl/src/main/java/com/force/formula/impl/FormulaParserImpl.java): `impl/src/main/java/com/force/formula/impl/FormulaParserImpl.java`
- [Formula commands](https://github.com/salesforce/formula-engine/tree/main/impl/src/main/java/com/force/formula/commands): `impl/src/main/java/com/force/formula/commands`
- [Compiled formula](https://github.com/salesforce/formula-engine/blob/main/impl/src/main/java/com/force/formula/impl/FormulaImpl.java): `impl/src/main/java/com/force/formula/impl/FormulaImpl.java`
- [Template functions](https://github.com/salesforce/formula-engine/tree/main/impl/src/main/java/com/force/formula/template/commands): `impl/src/main/java/com/force/formula/template/commands`

### Evaluation and contexts

- [Data context](https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaContext.java): `api/src/main/java/com/force/formula/FormulaContext.java`
- [Runtime context](https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaRuntimeContext.java): `api/src/main/java/com/force/formula/FormulaRuntimeContext.java`
- [Schema metadata](https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/FormulaSchema.java): `api/src/main/java/com/force/formula/FormulaSchema.java`

### Output generation

- [SQL generation API](https://github.com/salesforce/formula-engine/blob/main/api/src/main/java/com/force/formula/sql/FormulaSQLProvider.java): `api/src/main/java/com/force/formula/sql/FormulaSQLProvider.java`
- [SQL dialect hooks](https://github.com/salesforce/formula-engine/tree/main/impl/src/main/java/com/force/formula/impl/sql): `impl/src/main/java/com/force/formula/impl/sql`
- [JavaScript runtime](https://github.com/salesforce/formula-engine/blob/main/impl/src/main/resources/com/force/formula/formulaEngine.js): `impl/src/main/resources/com/force/formula/formulaEngine.js`

### Other components

- **Application**

## Connections

- Application → Engine hooks: configures (evidence: `README.md`)
- Application → Formula type config: implements (evidence: `README.md`)
- Application → Data types: implements (evidence: `README.md`)
- Application → Data context: provides (evidence: `README.md`)
- Application → Formula factory: customizes (evidence: `README.md`)
- Formula factory → Formula parser: compiles
- Application → Compiled formula: creates (evidence: `README.md`)
- Compiled formula → Runtime context: evaluates with (evidence: `README.md`)
- Data context → Schema metadata: exposes (evidence: `api/src/main/java/com/force/formula/FormulaContext.java`)
- Compiled formula → SQL generation API: generates SQL (evidence: `README.md`)
- SQL generation API → SQL dialect hooks: uses dialects
- Compiled formula → JavaScript runtime: generates JavaScript (evidence: `README.md`)
- Application → Template functions: extends with
