# jwadhams/json-logic-js architecture

> Architecture diagram of the GitHub repository jwadhams/json-logic-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jwadhams/json-logic-js
- Repository: https://github.com/jwadhams/json-logic-js

## Overview

##### Project type and purpose
- This is a standalone JavaScript library (“json-logic-js”) that implements a JsonLogic parser and executor.
- Its primary purpose is to take a JSON-encoded rule plus a JSON data object, evaluate the rule against the data, and return a result. It is distributed as a UMD module so it can run in Node.js, AMD loaders (RequireJS), or directly in the browser.

##### Main components of the system
a. UMD Loader/Module Wrapper
- Detects the environment (CommonJS, AMD, or global browser) and exports the `jsonLogic` object accordingly.
b. Core Engine (logic.js)
- The “apply” function: entry point for rule evaluation.
- Operations Registry: a mapping from operator-name strings (e.g. “==”, “and”, “var”) to handler functions.
- Evaluation Engine: interprets a rule object by looking up the operator in the registry, recursively evaluating its arguments, and returning the result.
c. Extension Point
- `jsonLogic.add_operation(name, fn)` lets you register custom operators.
d. Test Suite (tests/tests.js)
- Unit tests that load the module, feed it various rules/data, and verify the returned results.
e. Demo UI (play.html)
- A simple browser page that loads logic.js, takes user-entered rule and data JSON in textareas, calls `jsonLogic.apply`, and displays the result.

##### Relationships and data flow
- Consumer (Node app, browser app, or demo UI)
→ supplies → JsonLogic Engine (`jsonLogic.apply(rule, data)`)
→ engine uses → Operation Registry (built-ins + custom ops)
→ returns → primitive or structured result
- Test Runner
→ invokes → `jsonLogic.apply` with predefined rules/data
→ asserts correctness
- Extension code
→ calls → `jsonLogic.add_operation`
→ augments → Operation Registry

##### Architectural patterns and design principles
- Pluggable registry of operations (Strategy pattern).
- Environment-agnostic packaging (UMD).
- Single-responsibility core: logic.js contains only evaluation code, with no external dependencies.
- Separation of concerns: tests isolated in `/tests`, demo UI in `play.html`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "json-logic-js (logic.js)"
        UMD["UMD Loader/Module Wrapper"]:::packaging
        Engine["Evaluation Engine (apply)"]:::core
        Registry["Operation Registry"]:::core
    end

    NodeConsumer["Node.js App"]:::external
    AMDConsumer["AMD Loader (RequireJS)"]:::external
    BrowserConsumer["Browser Global"]:::external
    DemoUI["Demo UI (play.html)"]:::testdemo
    CustomOps["Custom Operations\n(jsonLogic.add_operation)"]:::custom
    TestSuite["Test Suite"]:::testdemo

    NodeConsumer -->|"rule + data in"| Engine
    AMDConsumer -->|"rule + data in"| Engine
    BrowserConsumer -->|"rule + data in"| Engine
    DemoUI -->|"rule + data in"| Engine

    Engine -->|"lookup operation"| Registry
    Engine -->|"returns result"| NodeConsumer
    Engine -->|"returns result"| AMDConsumer
    Engine -->|"returns result"| BrowserConsumer
    Engine -->|"returns result"| DemoUI

    CustomOps -->|"register op"| Registry
    TestSuite -->|"test invocation"| Engine

    click UMD "https://github.com/jwadhams/json-logic-js/blob/master/logic.js"
    click Engine "https://github.com/jwadhams/json-logic-js/blob/master/logic.js"
    click Registry "https://github.com/jwadhams/json-logic-js/blob/master/logic.js"
    click CustomOps "https://github.com/jwadhams/json-logic-js/blob/master/logic.js"
    click TestSuite "https://github.com/jwadhams/json-logic-js/blob/master/tests/tests.js"
    click DemoUI "https://github.com/jwadhams/json-logic-js/blob/master/play.html"

    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef packaging fill:#bbf,stroke:#333,stroke-width:1px
    classDef testdemo fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
    classDef custom fill:#ffb,stroke:#333,stroke-width:1px
```
