# simd-lite/simd-json architecture

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

- Interactive diagram: https://gitdiagram.com/simd-lite/simd-json
- Repository: https://github.com/simd-lite/simd-json

## Overview

This project is a high-performance Rust library for JSON parsing that leverages hardware SIMD instructions. In essence, it is a port of the simdjson C++ library, redesigned to work naturally in the Rust ecosystem. The core purpose is to parse JSON data as quickly as possible by using different optimized code paths (AVX2, SSE4.2, NEON, SIMD128) while also offering familiar APIs for both Serde and a DOM-like interface.

##### And delineate the main components
- Core Parsing Engine – Show the central “Parser” that receives raw JSON bytes and produces a parsed representation.
- SIMD Optimized Implementations – Lay out the various modules under src/impls:
- AVX2
- SSE4.2
- NEON
- SIMD128
- Native / fallback implementation
- API Layers – Identify the different usage entry points:
- Values API (Borrowed and Owned Values, implemented under src/value and related directories)
- Tape API (responsible for converting JSON to an intermediate “tape” representation in src/value/tape)
- Serde Compatible API (located in src/serde, enabling integration with Serde)
- Auxiliary Components – Include error handling (modules like src/error.rs), number parsing (in src/numberparse), string parsing (src/stringparse, charutils) and portability support.

##### Relationships and interactions
- Within the Core Parsing Engine, use a decision diamond to direct execution to the appropriate SIMD module (AVX2, SSE42, NEON, SIMD128) based on platform detection (enabled by the “runtime-detection” feature) or to a fallback native implementation.
- For experimental or auxiliary modules (like fuzzing targets in the fuzz folder and benchmark tests in benches), include a side note or peripheral components block indicating testing/validation subsystems.

##### Architectural patterns and important design principles
- Component separation: Clearly show a layered design where the API layer is separated from the core SIMD-optimized parsing logic.
- Runtime detection: Represent with a decision or switch mechanism that selects the appropriate optimized backend based on the detected CPU features.
- Safety vs. performance trade-offs: Note where “unsafe” code is used (primarily in SIMD intrinsics) and where additional unit tests and fuzzing in tests/ and fuzz/ ensure resilience.
- Feature toggles: Indicate optional features such as “serde_impl”, “swar-number-parsing”, “known-key”, etc., that modify behavior or integrate additional libraries.

##### Relevant details on technologies and frameworks
- Rust and the Cargo build system including the project’s Cargo.toml.
- Integration with build and CI/CD: The .github and .drone files indicate automated testing and quality checks.
- Dependency on specific allocators (mimalloc, jemalloc, or snmalloc) for better performance.
- Use of SIMD intrinsics: Mark the modules (in src/impls) that wrap hardware-specific instructions.

- Clear labels for each major component (for example: “API Entry Points”, “Runtime SIMD Detection”, “AVX2 Implementation”, “Serde Adapter”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: API Entry Points
    subgraph "API Layer"
        values["Values API"]:::api
        tape["Tape API"]:::api
        serde["Serde Adapter"]:::api
    end

    %% Middle Layer: Core Parser Engine and SIMD Selection
    coreEngine["Core Parsing Engine"]:::core
    values --> coreEngine
    tape --> coreEngine
    serde --> coreEngine

    simdDecision{"SIMD Backend Selection"}:::decision
    coreEngine --> simdDecision

    %% Lower Layer: SIMD Implementations
    subgraph "SIMD Implementations"
        AVX2["AVX2 Implementation"]:::simd
        SSE["SSE4.2 Implementation"]:::simd
        NEON["NEON Implementation"]:::simd
        SIMD128["SIMD128 Implementation"]:::simd
        fallback["Fallback Native Implementation"]:::simd
    end

    simdDecision -->|"AVX2"| AVX2
    simdDecision -->|"SSE4.2"| SSE
    simdDecision -->|"NEON"| NEON
    simdDecision -->|"SIMD128"| SIMD128
    simdDecision -->|"Fallback"| fallback

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        error["Error Handling"]:::aux
        number["Number Parsing"]:::aux
        string["String Parsing"]:::aux
        portability["Portability Support"]:::aux
    end

    coreEngine --- error
    coreEngine --- number
    coreEngine --- string
    coreEngine --- portability

    %% Testing and Integration Side Components
    subgraph "Testing & Integration"
        fuzz["Fuzzing & Tests"]:::test
        bench["Benchmark Tests"]:::test
        cicd["CI/CD Configurations"]:::test
    end

    coreEngine --- fuzz
    coreEngine --- bench
    coreEngine --- cicd

    %% Click Events
    click coreEngine "https://github.com/simd-lite/simd-json/blob/main/src/lib.rs"
    click AVX2 "https://github.com/simd-lite/simd-json/tree/main/src/impls/avx2/"
    click SSE "https://github.com/simd-lite/simd-json/tree/main/src/impls/sse42/"
    click NEON "https://github.com/simd-lite/simd-json/tree/main/src/impls/neon/"
    click SIMD128 "https://github.com/simd-lite/simd-json/tree/main/src/impls/simd128/"
    click fallback "https://github.com/simd-lite/simd-json/tree/main/src/impls/native/"
    click values "https://github.com/simd-lite/simd-json/tree/main/src/value/"
    click tape "https://github.com/simd-lite/simd-json/tree/main/src/value/tape/"
    click serde "https://github.com/simd-lite/simd-json/tree/main/src/serde/"
    click error "https://github.com/simd-lite/simd-json/blob/main/src/error.rs"
    click number "https://github.com/simd-lite/simd-json/blob/main/src/numberparse.rs"
    click string "https://github.com/simd-lite/simd-json/blob/main/src/stringparse.rs"
    click portability "https://github.com/simd-lite/simd-json/blob/main/src/portability.rs"

    %% Styling
    classDef api fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef core fill:#82E0AA,stroke:#1E8449,stroke-width:2px;
    classDef decision fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef simd fill:#F5B7B1,stroke:#CB4335,stroke-width:2px;
    classDef aux fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef test fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
