# json-iterator/go architecture

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

- Interactive diagram: https://gitdiagram.com/json-iterator/go
- Repository: https://github.com/json-iterator/go

## Overview

##### Main Components
- Client Interface Layer: This is the API exposed to users, where the configuration (e.g., ConfigCompatibleWithStandardLibrary) is defined. This acts as the entry-point for json.Marshal and json.Unmarshal calls.
- Core JSON Engine: Represented by files like jsoniter.go, adapter.go, and config.go, this is where the main logic of the library resides, handling JSON encoding and decoding.
- Iteration and Parsing Modules: Files like iter.go (and its variants such as iter_array.go, iter_object.go, iter_float.go, etc.) form a key module for traversing JSON structures efficiently.
- Stream Processing: With files like stream.go, stream_int.go, and stream_str.go, this module manages reading/writing JSON in a streamed fashion.
- Reflection-Based Conversion: Represented by numerous “reflect” files (reflect.go, reflect_array.go, reflect_struct_encoder.go, etc.), this module supports dynamic JSON marshaling and unmarshaling when reflection is needed.
- Extension and Adapter Modules: Extra components such as those in the "extra" directory (e.g., naming_strategy.go, binary_as_string_codec.go) extend the core functionality and fine-tune performance or compatibility.
- Testing & Benchmarking: Multiple directories (any_tests, api_tests, extension_tests, misc_tests, skip_tests, type_tests, value_tests) along with “benchmarks” clearly indicate rigorous testing and performance evaluation. Although not part of the deployment architecture, they reinforce the design’s emphasis on correctness and performance validation.
- Build & Configuration: A set of configuration files (Gopkg.toml, build.sh, .travis.yml, etc.) and dependency management files (Gopkg.lock, go.mod, go.sum) represent the infrastructure supporting continuous integration and dependency control.

##### Relationships and Interactions
- The Client Interface Layer calls into the Core JSON Engine which then dispatches work to underlying modules.
- The Core JSON Engine routes JSON data to either the Iteration/Parser modules or the Reflection modules based on data types and configuration.
- The Stream module operates as a specialized channel for large or continuously flowing JSON streams.
- Extension components act as plug-ins or adapters that can override or extend default behaviors.
- Testing components verify the behavior of each core module and the integration between them while benchmarks provide performance metrics.

##### Important Architectural Patterns/Principles
- Separation of Concerns: Each component (parsing, streaming, reflection, extensions) is isolated with a clear responsibility.
- Modular Design: The codebase is structured into multiple small modules/files (each handling a specific facet of JSON encoding/decoding) that inter-operate.
- Performance Optimization: The presence of multiple “iter” modules, “stream” modules, and benchmarking tests indicates a design heavily optimized for speed and low memory allocation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Interface Layer"
        CI["Client API: Marshal/Unmarshal"]:::external
        C1["jsoniter.go"]:::client
        C2["config.go"]:::client
    end

    subgraph "Core JSON Engine"
        CE["Core JSON Engine"]:::core
        CE1["adapter.go"]:::core
        CE2["config.go"]:::core
        CE3["jsoniter.go"]:::core
    end

    subgraph "Iteration and Parsing Modules"
        IP["Iteration/Parsing"]:::module
        IP1["iter.go"]:::module
        IP2["iter_array.go"]:::module
        IP3["iter_float.go"]:::module
        IP4["iter_int.go"]:::module
        IP5["iter_object.go"]:::module
        IP6["iter_skip.go"]:::module
        IP7["iter_skip_sloppy.go"]:::module
        IP8["iter_skip_strict.go"]:::module
        IP9["iter_str.go"]:::module
    end

    subgraph "Stream Processing"
        SP["Stream Processing"]:::module
        SP1["stream.go"]:::module
        SP2["stream_float.go"]:::module
        SP3["stream_int.go"]:::module
        SP4["stream_str.go"]:::module
    end

    subgraph "Reflection-Based Conversion"
        RB["Reflection Conversion"]:::module
        RB1["reflect.go"]:::module
        RB2["reflect_array.go"]:::module
        RB3["reflect_dynamic.go"]:::module
        RB4["reflect_extension.go"]:::module
        RB5["reflect_json_number.go"]:::module
        RB6["reflect_json_raw_message.go"]:::module
        RB7["reflect_map.go"]:::module
        RB8["reflect_marshaler.go"]:::module
        RB9["reflect_native.go"]:::module
        RB10["reflect_optional.go"]:::module
        RB11["reflect_slice.go"]:::module
        RB12["reflect_struct_decoder.go"]:::module
        RB13["reflect_struct_encoder.go"]:::module
    end

    subgraph "Extension and Adapter Modules"
        EA["Extensions/Adapters"]:::module
        EA1["binary_as_string_codec.go"]:::module
        EA2["fuzzy_decoder.go"]:::module
        EA3["naming_strategy.go"]:::module
        EA4["privat_fields.go"]:::module
        EA5["time_as_int64_codec.go"]:::module
    end

    subgraph "Testing & Benchmarking"
        TB["Testing & Benchmarking"]:::test
        TB1["any_tests/"]:::test
        TB2["api_tests/"]:::test
        TB3["benchmarks/"]:::test
        TB4["extension_tests/"]:::test
        TB5["misc_tests/"]:::test
        TB6["skip_tests/"]:::test
        TB7["type_tests/"]:::test
        TB8["value_tests/"]:::test
        TB9["example_test.go"]:::test
        TB10["test.sh"]:::test
    end

    subgraph "Build & Configuration"
        BC["Build & Configuration"]:::ci
        BC1["Gopkg.toml"]:::ci
        BC2["Gopkg.lock"]:::ci
        BC3["go.mod"]:::ci
        BC4["go.sum"]:::ci
        BC5["build.sh"]:::ci
        BC6[".travis.yml"]:::ci
        BC7[".codecov.yml"]:::ci
    end

    %% Data Flow Connections
    CI -->|"calls"| CE
    CE -->|"routes to"| IP
    CE -->|"routes to"| SP
    CE -->|"routes to"| RB
    CE -->|"integrates"| EA

    %% Validation and CI support
    TB ---|"validates"| CE
    BC ---|"supports"| CE

    %% Click Events for Client Interface Layer
    click C1 "https://github.com/json-iterator/go/blob/master/jsoniter.go"
    click C2 "https://github.com/json-iterator/go/blob/master/config.go"

    %% Click Events for Core JSON Engine
    click CE3 "https://github.com/json-iterator/go/blob/master/jsoniter.go"
    click CE1 "https://github.com/json-iterator/go/blob/master/adapter.go"
    click CE2 "https://github.com/json-iterator/go/blob/master/config.go"

    %% Click Events for Iteration and Parsing Modules
    click IP1 "https://github.com/json-iterator/go/blob/master/iter.go"
    click IP2 "https://github.com/json-iterator/go/blob/master/iter_array.go"
    click IP3 "https://github.com/json-iterator/go/blob/master/iter_float.go"
    click IP4 "https://github.com/json-iterator/go/blob/master/iter_int.go"
    click IP5 "https://github.com/json-iterator/go/blob/master/iter_object.go"
    click IP6 "https://github.com/json-iterator/go/blob/master/iter_skip.go"
    click IP7 "https://github.com/json-iterator/go/blob/master/iter_skip_sloppy.go"
    click IP8 "https://github.com/json-iterator/go/blob/master/iter_skip_strict.go"
    click IP9 "https://github.com/json-iterator/go/blob/master/iter_str.go"

    %% Click Events for Stream Processing
    click SP1 "https://github.com/json-iterator/go/blob/master/stream.go"
    click SP2 "https://github.com/json-iterator/go/blob/master/stream_float.go"
    click SP3 "https://github.com/json-iterator/go/blob/master/stream_int.go"
    click SP4 "https://github.com/json-iterator/go/blob/master/stream_str.go"

    %% Click Events for Reflection-Based Conversion
    click RB1 "https://github.com/json-iterator/go/blob/master/reflect.go"
    click RB2 "https://github.com/json-iterator/go/blob/master/reflect_array.go"
    click RB3 "https://github.com/json-iterator/go/blob/master/reflect_dynamic.go"
    click RB4 "https://github.com/json-iterator/go/blob/master/reflect_extension.go"
    click RB5 "https://github.com/json-iterator/go/blob/master/reflect_json_number.go"
    click RB6 "https://github.com/json-iterator/go/blob/master/reflect_json_raw_message.go"
    click RB7 "https://github.com/json-iterator/go/blob/master/reflect_map.go"
    click RB8 "https://github.com/json-iterator/go/blob/master/reflect_marshaler.go"
    click RB9 "https://github.com/json-iterator/go/blob/master/reflect_native.go"
    click RB10 "https://github.com/json-iterator/go/blob/master/reflect_optional.go"
    click RB11 "https://github.com/json-iterator/go/blob/master/reflect_slice.go"
    click RB12 "https://github.com/json-iterator/go/blob/master/reflect_struct_decoder.go"
    click RB13 "https://github.com/json-iterator/go/blob/master/reflect_struct_encoder.go"

    %% Click Events for Extension and Adapter Modules
    click EA1 "https://github.com/json-iterator/go/blob/master/extra/binary_as_string_codec.go"
    click EA2 "https://github.com/json-iterator/go/blob/master/extra/fuzzy_decoder.go"
    click EA3 "https://github.com/json-iterator/go/blob/master/extra/naming_strategy.go"
    click EA4 "https://github.com/json-iterator/go/blob/master/extra/privat_fields.go"
    click EA5 "https://github.com/json-iterator/go/blob/master/extra/time_as_int64_codec.go"

    %% Click Events for Testing & Benchmarking
    click TB1 "https://github.com/json-iterator/go/tree/master/any_tests/"
    click TB2 "https://github.com/json-iterator/go/tree/master/api_tests/"
    click TB3 "https://github.com/json-iterator/go/tree/master/benchmarks/"
    click TB4 "https://github.com/json-iterator/go/tree/master/extension_tests/"
    click TB5 "https://github.com/json-iterator/go/tree/master/misc_tests/"
    click TB6 "https://github.com/json-iterator/go/tree/master/skip_tests/"
    click TB7 "https://github.com/json-iterator/go/tree/master/type_tests/"
    click TB8 "https://github.com/json-iterator/go/tree/master/value_tests/"
    click TB9 "https://github.com/json-iterator/go/blob/master/example_test.go"
    click TB10 "https://github.com/json-iterator/go/blob/master/test.sh"

    %% Click Events for Build & Configuration
    click BC1 "https://github.com/json-iterator/go/blob/master/Gopkg.toml"
    click BC2 "https://github.com/json-iterator/go/blob/master/Gopkg.lock"
    click BC3 "https://github.com/json-iterator/go/blob/master/go.mod"
    click BC4 "https://github.com/json-iterator/go/blob/master/go.sum"
    click BC5 "https://github.com/json-iterator/go/blob/master/build.sh"
    click BC6 "https://github.com/json-iterator/go/blob/master/.travis.yml"
    click BC7 "https://github.com/json-iterator/go/blob/master/.codecov.yml"

    %% Class Definitions for colour and style
    classDef external fill:#CDEB8B,stroke:#333,stroke-width:2px;
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef core fill:#FAD02E,stroke:#333,stroke-width:2px;
    classDef module fill:#BEE3DB,stroke:#333,stroke-width:2px;
    classDef test fill:#E8A0BF,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef ci fill:#C0C0C0,stroke:#333,stroke-width:2px,stroke-dasharray: 3 3;
```
