# json-iterator/java architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source Java library (“json-iterator/java”) for high-performance JSON parsing and serialization.
- It provides:
- A runtime JSON iterator (JsonIterator) and streaming API (JsonStream).
- Multiple code generation strategies (static, dynamic, SPI-based).
- Extension modules for compatibility (Gson, Jackson), extras (Base64, datetime), fuzzy parsing, “any” type support, etc.
- It includes two sample applications (demo and android-demo) to illustrate usage and codegen integration.

##### File Structure Analysis
Top-level
- pom.xml, Travis and CI config, LICENSE, CHANGELOG, README.
- android-demo/ (Android Studio sample).
- demo/ (Maven console sample).
- src/ (core library).
Core src/main/java/com/jsoniter
- Codegen packages: static_codegen, jsoniter_codegen, output.codegen…
- Runtime iterator packages: JsonIterator, IterImpl*, MapKeyDecoders, JsonIteratorPool.
- SPI: Config, Decoder, Encoder, Extension interfaces.
- any/: dynamic “Any” type support with lazy, wrapper variants.
- extra/: plug-in modules for compatibility and naming strategies.
- fuzzy/: tolerant decoder implementations.
- output/: streaming encoder, JsonStream, JsonStreamPool.
Tests
- Extensive unit tests under src/test for all modules and sample data.

- Core Runtime: JsonIterator, IterImpl*, MapKeyDecoders, JsonIteratorPool.
- Code Generation:
– StaticCodegen (compile-time generator).
– DynamicCodegen (runtime bytecode generator).
– jsoniter_codegen (annotation-driven source generator).
- Streaming API: JsonStream, JsonStreamPool, encoding/decoding impls.
- SPI & Extensions:
– SPI interfaces (Decoder, Encoder, Extension).
– extra/ modules (GsonCompatibilityMode, JacksonCompatibilityMode, etc.).
– fuzzy/ parsers.
– any/ “Any” API.
- Samples & Build:
– demo/ (Maven-driven CLI demo).
– android-demo/ (Android sample using Gradle).
- External Dependencies:
– JDK, ASM or equivalent bytecode libs (if used), annotation processors.

- Application code → JsonIterator (entry point) → IterImpl* → core byte array/buffer.
- Application code → Codegen module → generates encoder/decoder classes → classloader.
- JsonStream ↔ JsonStreamPool (object reuse), writes to OutputStream.
- SPI interfaces ← Extension implementations (extra/, fuzzy/).
- Samples invoke either static_codegen or dynamic_codegen to pre-generate or on-the-fly generate serializers.

c. Architectural Patterns & Principles
- Factory/Provider pattern: CodegenAccess, ReflectionDecoderFactory for selecting decoding strategy.
- SPI: decouples core from extension modules.
- Pooling: JsonIteratorPool, JsonStreamPool for object reuse and performance.
- Modular design: clear separation between parsing (iterators), serialization (streams), codegen, and extension.

d. Key Technologies & Frameworks
- Java 8+ (annotations, reflection).
- Maven (core build) and Gradle (android-demo).
- Annotation processing for code generation.
- Streaming I/O APIs.
- ASM or similar for dynamic class generation (implicit).

##### Essential Elements to Capture
- Core entry points (JsonIterator, JsonStream).
- Codegen paths (static vs dynamic vs annotation-based).
- SPI interfaces and sample extension modules.
- Consumer apps demonstrating integration.
- Object pools for performance.
- External I/O (InputStream, OutputStream).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Runtime
    subgraph "Core Runtime" 
        direction TB
        JI["JsonIterator"]:::core
        I1["IterImpl"]:::core
        I2["IterImplArray"]:::core
        I3["IterImplNumber"]:::core
        I4["IterImplObject"]:::core
        I5["IterImplSkip"]:::core
        I6["IterImplString"]:::core
        MKD["MapKeyDecoders"]:::core
        JIP["JsonIteratorPool"]:::core
    end

    %% Code Generation
    subgraph "Code Generation" 
        direction TB
        SC["StaticCodegen"]:::codegen
        SCfg["StaticCodegenConfig"]:::codegen
        DC["DynamicCodegen"]:::codegen
        CA["CodegenAccess"]:::codegen
        CIArray["CodegenImplArray"]:::codegen
        CIEnum["CodegenImplEnum"]:::codegen
        CIMap["CodegenImplMap"]:::codegen
        CINative["CodegenImplNative"]:::codegen
        CIObjHash["CodegenImplObjectHash"]:::codegen
        CIObjStrict["CodegenImplObjectStrict"]:::codegen
    end

    %% Streaming API
    subgraph "Streaming API"
        direction TB
        JS["JsonStream"]:::stream
        JSP["JsonStreamPool"]:::stream
        SE["StreamImplNumber"]:::stream
        SS["StreamImplString"]:::stream
        MKE["MapKeyEncoders"]:::stream
        RE["ReflectionEncoder*"]:::stream
    end

    %% SPI & Extensions
    subgraph "SPI & Extensions"
        direction TB
        subgraph "SPI Interfaces"
            direction TB
            DEC["Decoder"]:::spi
            ENC["Encoder"]:::spi
            EXT["Extension"]:::spi
            CFG["Config"]:::spi
        end
        subgraph "Extra Modules"
            direction TB
            GSM["GsonCompatibilityMode"]:::extension
            JCM["JacksonCompatibilityMode"]:::extension
            B64["Base64Support"]:::extension
            JDKDT["JdkDatetimeSupport"]:::extension
            NS["NamingStrategySupport"]:::extension
            PFS["PreciseFloatSupport"]:::extension
        end
        subgraph "Fuzzy Parsers"
            direction TB
            FZD["StringIntDecoder"]:::extension
        end
        subgraph "Any API"
            direction TB
            ANY["Any"]:::extension
        end
    end

    %% Consumers
    subgraph "Consumers"
        direction TB
        Demo["Demo CLI"]:::consumer
        ADemo["Android Demo"]:::consumer
    end

    %% Relationships
    Demo -->|"uses"| JI
    ADemo -->|"uses"| JI
    Demo -->|"triggers"| SC
    ADemo -->|"triggers"| DC
    JI -->|"delegates to"| I1
    JI -->|"delegates to"| I2
    JI -->|"delegates to"| I3
    JI -->|"delegates to"| I4
    JI -->|"delegates to"| I5
    JI -->|"delegates to"| I6
    I* -->|"uses decoder"| MKD
    JI -->|"obtains from"| JIP
    SC -->|"calls"| CA
    DC -->|"calls"| CA
    CA -->|"generates classes for"| JI
    JS -->|"reuses from"| JSP
    JS -->|"writes to"| OutputStream[("OutputStream")]:::io
    SC -->|"produces"| CIArray
    SC -->|"produces"| CIEnum
    SC -->|"produces"| CIMap
    SC -->|"produces"| CINative
    SC -->|"produces"| CIObjHash
    SC -->|"produces"| CIObjStrict
    DEC <-->|"implemented by"| GSM
    DEC <-->|"implemented by"| JCM
    DEC <-->|"implemented by"| B64
    DEC <-->|"implemented by"| JDKDT
    DEC <-->|"implemented by"| NS
    DEC <-->|"implemented by"| PFS
    DEC <-->|"implemented by"| FZD
    DEC <-->|"implemented by"| ANY

    %% Click Events
    click JI "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/JsonIterator.java"
    click I1 "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/IterImpl.java"
    click I2 "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/IterImplArray.java"
    click I3 "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/IterImplNumber.java"
    click I4 "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/IterImplObject.java"
    click I5 "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/IterImplSkip.java"
    click I6 "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/IterImplString.java"
    click MKD "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/MapKeyDecoders.java"
    click JIP "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/JsonIteratorPool.java"
    click SC "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/static_codegen/StaticCodegen.java"
    click SCfg "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/static_codegen/StaticCodegenConfig.java"
    click DC "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/DynamicCodegen.java"
    click CA "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/CodegenAccess.java"
    click CIArray "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/CodegenImplArray.java"
    click CIEnum "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/CodegenImplEnum.java"
    click CIMap "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/CodegenImplMap.java"
    click CINative "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/CodegenImplNative.java"
    click CIObjHash "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/CodegenImplObjectHash.java"
    click CIObjStrict "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/CodegenImplObjectStrict.java"
    click JS "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/output/JsonStream.java"
    click JSP "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/output/JsonStreamPool.java"
    click SE "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/output/StreamImplNumber.java"
    click SS "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/output/StreamImplString.java"
    click MKE "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/output/MapKeyEncoders.java"
    click DEC "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/spi/Decoder.java"
    click ENC "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/spi/Encoder.java"
    click EXT "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/spi/Extension.java"
    click CFG "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/spi/Config.java"
    click GSM "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/extra/GsonCompatibilityMode.java"
    click JCM "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/extra/JacksonCompatibilityMode.java"
    click B64 "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/extra/Base64Support.java"
    click JDKDT "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/extra/JdkDatetimeSupport.java"
    click NS "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/extra/NamingStrategySupport.java"
    click PFS "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/extra/PreciseFloatSupport.java"
    click FZD "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/fuzzy/StringIntDecoder.java"
    click ANY "https://github.com/json-iterator/java/blob/master/src/main/java/com/jsoniter/any/Any.java"
    click Demo "https://github.com/json-iterator/java/blob/master/demo/src/main/java/com/jsoniter/demo/Demo.java"
    click ADemo "https://github.com/json-iterator/java/blob/master/android-demo/src/main/java/com/example/myapplication/MainActivity.java"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef codegen fill:#d4edda,stroke:#155724,color:#155724
    classDef stream fill:#fff3cd,stroke:#856404,color:#856404
    classDef spi fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef extension fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00
    classDef consumer fill:#f8f9fa,stroke:#6c757d,color:#343a40
    classDef io fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
