# tidwall/gjson architecture

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

- Interactive diagram: https://gitdiagram.com/tidwall/gjson
- Repository: https://github.com/tidwall/gjson

## Overview

##### Project Type and Purpose
- This is an open-source Go library (package) named GJSON for fast, read-only querying of JSON documents.
- It is not a full-stack web app but a specialized utility library offering:
- A simple API (Get, GetBytes, Parse, Valid)
- A path-syntax engine (dot notation, wildcards, queries)
- A modifiers system (built-in and user-defined)
- JSON Lines support and iteration helpers
- Its goal is to provide a minimal-allocation, zero-panic JSON query tool.

##### File Structure Analysis
- gjson.go: core implementation of API, parser, path engine, modifiers registry, Result type.
- gjson_test.go: unit tests exercising API, syntax, edge-cases.
- SYNTAX.md: detailed documentation for the path-syntax grammar.
- README.md: overview, examples, performance benchmarks.
- go.mod / go.sum: module dependencies.
- .github/workflows/go.yml: CI setup for Go tests.
- LICENSE: open-source license.

a. Public API Layer
- Functions: Get, GetBytes, Parse, Valid, ForEachLine
- Entry points into the system
b. Path Syntax Engine
- Path parser that tokenizes dot notation, wildcards, queries
- Query evaluator for expressions (#(...), comparisons, pattern matching)
c. JSON Parser & Traversal
- Minimal parsing: raw byte/string scanning for values
- Traversal logic to jump to JSON token positions via indexes
d. Result Model
- Result struct fields (Type, Str, Num, Raw, Index, Indexes)
- Helper methods: Exists, Value, Array, Map, Int/Uint, ForEach
e. Modifiers System
- Built-in modifiers registry (@reverse, @pretty, etc.)
- Extension point: AddModifier hook for custom functions
- Modifier pipeline: pipe (‘|’) chaining between path segments
f. JSON Lines Support
- ForEachLine helper splitting input on newline and treating as array
g. Tests & CI
- gjson_test.go invoking API for correctness
- CI workflow: go.yml for linting and test runs

##### Relationships and Data Flow
1. Client code calls Public API →
2. (Optional) Invoke Valid or Parse → produces initial parse context →
3. Path Syntax Engine interprets the path string →
4. JSON Parser & Traversal uses parsed tokens to locate matches in the JSON input →
5. Modifiers System (if any) post-processes intermediate JSON snippets →
6. Result Model is populated and returned to client →
7. ForEachLine iterates over JSON Lines, looping back through steps 2–6
8. Tests import Public API and verify expected output

##### Architectural Patterns and Principles
- Single Responsibility: each component has a clear duty (API, parsing, syntax, modifiers, result).
- Lazy evaluation: stops at first match when possible, zero allocations where feasible.
- Extensibility: modifiers registry decoupled from core engine.
- Separation of concerns: path parsing is distinct from JSON traversal.

##### Technologies and Frameworks
- Language: Go
- Testing: Go’s built-in testing package
- CI: GitHub Actions using go.yml
- Documentation: Markdown (README.md, SYNTAX.md)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    A["Client Code"]:::external

    %% Data Inputs
    Input["Input JSON"]:::data
    Path["Path String"]:::data

    %% Core Modules
    subgraph "Core Modules"
        API["Public API Layer"]:::module
        Syntax["Path Syntax Engine"]:::module
        Parser["JSON Parser & Traversal"]:::module
        ModSys["Modifiers System"]:::module
        ResultModel["Result Model"]:::module
        JSONLines["JSON Lines Support"]:::module
    end

    %% Data Output
    Return["Result"]:::data

    %% Documentation and Tests
    Docs1["README.md"]:::doc
    Docs2["SYNTAX.md"]:::doc
    Tests["gjson_test.go"]:::doc
    CI[".github/workflows/go.yml"]:::infra
    Deps["go.mod / go.sum"]:::infra
    License["LICENSE"]:::infra

    %% Flow
    A --> API
    Input --> API
    Path --> API
    API --> Syntax
    Syntax --> Parser
    Parser --> ModSys
    ModSys --> ResultModel
    ResultModel --> Return
    API --> JSONLines
    JSONLines --> Syntax

    %% Supporting Infra
    Tests -.-> API
    CI -.-> API
    Docs1 -.-> API
    Docs2 -.-> Syntax
    Deps -.-> API
    License -.-> API

    %% Click Events
    click API "https://github.com/tidwall/gjson/blob/master/gjson.go"
    click Syntax "https://github.com/tidwall/gjson/blob/master/gjson.go"
    click Parser "https://github.com/tidwall/gjson/blob/master/gjson.go"
    click ModSys "https://github.com/tidwall/gjson/blob/master/gjson.go"
    click ResultModel "https://github.com/tidwall/gjson/blob/master/gjson.go"
    click JSONLines "https://github.com/tidwall/gjson/blob/master/gjson.go"
    click Tests "https://github.com/tidwall/gjson/blob/master/gjson_test.go"
    click CI "https://github.com/tidwall/gjson/blob/master/.github/workflows/go.yml"
    click Docs1 "https://github.com/tidwall/gjson/blob/master/README.md"
    click Docs2 "https://github.com/tidwall/gjson/blob/master/SYNTAX.md"
    click Deps "https://github.com/tidwall/gjson/blob/master/go.mod"
    click License "https://github.com/tidwall/gjson/tree/master/LICENSE"

    %% Styles
    classDef module fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef doc fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef infra fill:#F0E68C,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#FFE4B5,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
