# h2non/jsonpath-ng architecture

> Architecture diagram of the GitHub repository h2non/jsonpath-ng, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/h2non/jsonpath-ng
- Repository: https://github.com/h2non/jsonpath-ng

## Overview

##### Main Components
- Core Parsing Engine: Represent the main JSONPath parser and lexer modules. Show how input JSONPath expressions are processed.
- Abstract Syntax Tree (AST) & Evaluation API: Highlight the creation of ASTs (as seen in jsonpath_ng/jsonpath.py and the AST API methods) and the mechanisms for traversing or modifying JSON objects.
- Extension Modules: Specifically identify the “ext” directory which contains extensions for arithmetic, filtering, string handling, and iterable operations. These modules extend the base JSONPath language.
- Command-Line Interface: The bin component (jsonpath_ng/bin/jsonpath.py) that allows the library to be used from the command line.
- Exception Handling: Modules (e.g., jsonpath_ng/exceptions.py) that manage errors during parsing or evaluation.
- Testing & Continuous Integration: Although not part of runtime, include a note on the “tests” directory and the CI/CD configurations (GitHub workflows, tox.ini, etc.) which assure code quality and integration.

##### Relationships and Interactions
- Input Flow: Start with a JSONPath expression provided by the user (via the CLI or programmatically). The expression is sent through the Lexer (jsonpath_ng/lexer.py), which tokenizes the input.
- Parsing Stage: Pass tokens to the Parser (jsonpath_ng/parser.py) for building the AST.
- AST Manipulation & Evaluation: The AST API (mainly in jsonpath_ng/jsonpath.py) uses the built structure to search, update, or remove nodes from a JSON document.
- Error Management: Exceptions are captured and processed by the exception module, ensuring that parsing or evaluation errors are reported clearly.
- Command Line Integration: The CLI component acts as a user interface that maps user commands into calls to the core library components.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize the separation of concerns – the lexical analysis, parsing, AST construction, evaluation, and extensions are clearly separated into different modules and packages.
- Testability and CI Integration: Although not runtime components, the existence of comprehensive tests and workflows (in GitHub/workflows, tox.ini, etc.) suggests an emphasis on reliability and continuous integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Group
    subgraph "User Interaction"
        UI("User Input (JSONPath Expression)"):::input
        CLI("CLI Interface"):::cli
    end

    UI --> CLI

    %% Core JSONPath Processing
    CLI --> LEXER("Lexer Module"):::core
    LEXER --> PARSER("Parser Module"):::core
    PARSER --> AST("AST & Evaluation Engine"):::core

    %% Extension Modules Subgraph
    subgraph "Extension Modules"
        ARITH("Arithmetic"):::ext
        FILTER("Filter"):::ext
        ITER("Iterable"):::ext
        EXTPAR("Parser Extension"):::ext
        STR("String"):::ext
    end

    %% Connections between Core and Extensions
    AST -->|"extension_hooks"| ARITH
    AST -->|"extension_hooks"| FILTER
    AST -->|"extension_hooks"| ITER
    AST -->|"extension_hooks"| EXTPAR
    AST -->|"extension_hooks"| STR
    ARITH -->|"enhanced_eval"| AST
    FILTER -->|"enhanced_eval"| AST
    ITER -->|"enhanced_eval"| AST
    EXTPAR -->|"enhanced_eval"| AST
    STR -->|"enhanced_eval"| AST

    %% Returning result from AST evaluation to CLI
    AST -->|"return_result"| CLI

    %% Exception Handling for errors
    LEXER -->|"error"| EXCEP("Exception Handler"):::exception
    PARSER -->|"error"| EXCEP
    AST -->|"error"| EXCEP

    %% Testing & CI/CD Subgraph
    subgraph "Testing & CI/CD"
        TST("Tests Directory"):::test
        WORKF("GitHub Workflows"):::test
        TOX("tox.ini"):::test
    end

    %% Click Events for Core Components
    click LEXER "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/lexer.py"
    click PARSER "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/parser.py"
    click AST "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/jsonpath.py"
    click CLI "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/bin/jsonpath.py"
    click EXCEP "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/exceptions.py"

    %% Click Events for Extension Modules
    click ARITH "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/ext/arithmetic.py"
    click FILTER "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/ext/filter.py"
    click ITER "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/ext/iterable.py"
    click EXTPAR "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/ext/parser.py"
    click STR "https://github.com/h2non/jsonpath-ng/blob/master/jsonpath_ng/ext/string.py"

    %% Click Events for Testing & CI/CD
    click TST "https://github.com/h2non/jsonpath-ng/tree/master/tests"
    click WORKF "https://github.com/h2non/jsonpath-ng/tree/master/.github/workflows"
    click TOX "https://github.com/h2non/jsonpath-ng/blob/master/tox.ini"

    %% Styles
    classDef input fill:#f9f,stroke:#333,stroke-width:2px,color:#000;
    classDef cli fill:#fdb,stroke:#333,stroke-width:2px,color:#000;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px,color:#000;
    classDef ext fill:#cfc,stroke:#333,stroke-width:2px,color:#000;
    classDef exception fill:#f99,stroke:#333,stroke-width:2px,color:#000;
    classDef test fill:#eee,stroke:#333,stroke-width:2px,color:#000;
```
