# simdjson/simdjson-java architecture

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

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

## Overview

simdjson-java is a Java SIMD-oriented JSON parsing library. An application supplies a byte buffer to SimdJsonParser, which validates UTF-8 and indexes structural characters before dispatching to either a DOM-producing iterator or a schema-based iterator; the result is a JsonValue tree or a typed Java object. The runtime also includes an on-demand iterator and specialized string, number, and schema-resolution logic. Relationships below follow the README and source-index references; unsampled implementation details are not inferred beyond those references.

Main entry points: [`src/main/java/org/simdjson/SimdJsonParser.java`](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/SimdJsonParser.java) (Parser API), [`src/main/java/org/simdjson/NumberParser.java`](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/NumberParser.java) (Number parser), [`src/main/java/org/simdjson/JsonIterator.java`](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/JsonIterator.java) (DOM iterator), [`src/main/java/org/simdjson/TapeBuilder.java`](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/TapeBuilder.java) (Tape builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Parsing entry"]
  node_parser["Parser API"]
  node_utf8["UTF-8 validation<br/>[Utf8Validator.java]"]
  node_indexer["Structural indexer"]
  node_bitindexes["Structural indexes<br/>[BitIndexes.java]"]
end

subgraph group_traversal["Document traversal"]
  node_domiterator["DOM iterator<br/>[JsonIterator.java]"]
  node_ondemand["On-demand iterator"]
  node_tapebuilder["Tape builder<br/>[TapeBuilder.java]"]
  node_tape["Value tape<br/>[Tape.java]"]
  node_jsonvalue["DOM values<br/>[JsonValue.java]"]
end

subgraph group_decoding["Value decoding"]
  node_stringparser["String decoder<br/>[StringParser.java]"]
  node_numberparser["Number parser<br/>[NumberParser.java]"]
  node_exponent["Exponent parser"]
  node_doubleparser["Floating conversion<br/>[DoubleParser.java]"]
  node_floatparser["Float conversion<br/>[FloatParser.java]"]
  node_numbertables["Number tables"]
  node_characters["Character utilities"]
  node_vectors["Vector utilities<br/>[VectorUtils.java]"]
  node_exception["Parse errors"]
end

subgraph group_schema["Schema mapping"]
  node_schemaiterator["Schema iterator"]
  node_classresolver["Class resolver<br/>[ClassResolver.java]"]
  node_resolvedclass["Resolved schema<br/>[ResolvedClass.java]"]
  node_arguments["Constructor arguments"]
end

node_application(("Application"))

node_application -->|"supplies JSON"| node_parser
node_parser -->|"validates bytes"| node_utf8
node_parser -->|"indexes structure"| node_indexer
node_indexer -->|"writes positions"| node_bitindexes
node_parser -->|"dispatches DOM parse"| node_domiterator
node_parser -->|"dispatches typed parse"| node_schemaiterator
node_domiterator -->|"builds tape"| node_tapebuilder
node_domiterator -->|"reads positions"| node_bitindexes
node_domiterator -->|"returns values"| node_jsonvalue
node_tapebuilder -->|"appends values"| node_tape
node_tapebuilder -->|"decodes strings"| node_stringparser
node_tapebuilder -->|"parses numbers"| node_numberparser
node_jsonvalue -->|"reads values"| node_tape
node_numberparser -->|"parses exponents"| node_exponent
node_numberparser -->|"converts doubles"| node_doubleparser
node_numberparser -->|"converts floats"| node_floatparser
node_doubleparser -->|"uses tables"| node_numbertables
node_floatparser -->|"uses tables"| node_numbertables
node_stringparser -->|"decodes escapes"| node_characters
node_stringparser -->|"uses SIMD vectors"| node_vectors
node_schemaiterator -->|"uses resolved schema"| node_resolvedclass
node_schemaiterator -->|"uses traversal"| node_ondemand
node_classresolver -->|"resolves classes"| node_resolvedclass
node_resolvedclass -->|"maps parameters"| node_arguments
node_numberparser -->|"raises parse errors"| node_exception

click node_parser "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/SimdJsonParser.java"
click node_utf8 "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/Utf8Validator.java"
click node_indexer "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/StructuralIndexer.java"
click node_bitindexes "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/BitIndexes.java"
click node_domiterator "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/JsonIterator.java"
click node_ondemand "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/OnDemandJsonIterator.java"
click node_schemaiterator "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/SchemaBasedJsonIterator.java"
click node_tapebuilder "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/TapeBuilder.java"
click node_tape "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/Tape.java"
click node_jsonvalue "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/JsonValue.java"
click node_stringparser "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/StringParser.java"
click node_numberparser "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/NumberParser.java"
click node_exponent "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/ExponentParser.java"
click node_doubleparser "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/DoubleParser.java"
click node_floatparser "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/FloatParser.java"
click node_numbertables "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/NumberParserTables.java"
click node_characters "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/CharacterUtils.java"
click node_vectors "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/VectorUtils.java"
click node_classresolver "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/ClassResolver.java"
click node_resolvedclass "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/ResolvedClass.java"
click node_arguments "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/ConstructorArgumentsMap.java"
click node_exception "https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/JsonParsingException.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parser,node_utf8,node_indexer,node_bitindexes toneBlue
class node_domiterator,node_ondemand,node_tapebuilder,node_tape,node_jsonvalue toneAmber
class node_stringparser,node_numberparser,node_exponent,node_doubleparser,node_floatparser,node_numbertables,node_characters,node_vectors,node_exception toneMint
class node_schemaiterator,node_classresolver,node_resolvedclass,node_arguments toneRose
class node_application toneIndigo
```

## Components

### Parsing entry

- [Parser API](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/SimdJsonParser.java): `src/main/java/org/simdjson/SimdJsonParser.java`
- [UTF-8 validation](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/Utf8Validator.java): `src/main/java/org/simdjson/Utf8Validator.java`
- [Structural indexer](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/StructuralIndexer.java): `src/main/java/org/simdjson/StructuralIndexer.java`
- [Structural indexes](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/BitIndexes.java): `src/main/java/org/simdjson/BitIndexes.java`

### Document traversal

- [DOM iterator](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/JsonIterator.java): `src/main/java/org/simdjson/JsonIterator.java`
- [On-demand iterator](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/OnDemandJsonIterator.java): `src/main/java/org/simdjson/OnDemandJsonIterator.java`
- [Tape builder](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/TapeBuilder.java): `src/main/java/org/simdjson/TapeBuilder.java`
- [Value tape](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/Tape.java): `src/main/java/org/simdjson/Tape.java`
- [DOM values](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/JsonValue.java): `src/main/java/org/simdjson/JsonValue.java`

### Value decoding

- [String decoder](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/StringParser.java): `src/main/java/org/simdjson/StringParser.java`
- [Number parser](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/NumberParser.java): `src/main/java/org/simdjson/NumberParser.java`
- [Exponent parser](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/ExponentParser.java): `src/main/java/org/simdjson/ExponentParser.java`
- [Floating conversion](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/DoubleParser.java): `src/main/java/org/simdjson/DoubleParser.java`
- [Float conversion](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/FloatParser.java): `src/main/java/org/simdjson/FloatParser.java`
- [Number tables](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/NumberParserTables.java): `src/main/java/org/simdjson/NumberParserTables.java`
- [Character utilities](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/CharacterUtils.java): `src/main/java/org/simdjson/CharacterUtils.java`
- [Vector utilities](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/VectorUtils.java): `src/main/java/org/simdjson/VectorUtils.java`
- [Parse errors](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/JsonParsingException.java): `src/main/java/org/simdjson/JsonParsingException.java`

### Schema mapping

- [Schema iterator](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/SchemaBasedJsonIterator.java): `src/main/java/org/simdjson/SchemaBasedJsonIterator.java`
- [Class resolver](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/ClassResolver.java): `src/main/java/org/simdjson/ClassResolver.java`
- [Resolved schema](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/ResolvedClass.java): `src/main/java/org/simdjson/ResolvedClass.java`
- [Constructor arguments](https://github.com/simdjson/simdjson-java/blob/main/src/main/java/org/simdjson/ConstructorArgumentsMap.java): `src/main/java/org/simdjson/ConstructorArgumentsMap.java`

### Other components

- **Application**

## Connections

- Application → Parser API: supplies JSON (evidence: `README.md`)
- Parser API → UTF-8 validation: validates bytes (evidence: `src/main/java/org/simdjson/SimdJsonParser.java`)
- Parser API → Structural indexer: indexes structure (evidence: `src/main/java/org/simdjson/SimdJsonParser.java`)
- Structural indexer → Structural indexes: writes positions (evidence: `src/main/java/org/simdjson/StructuralIndexer.java`)
- Parser API → DOM iterator: dispatches DOM parse (evidence: `src/main/java/org/simdjson/SimdJsonParser.java`)
- Parser API → Schema iterator: dispatches typed parse (evidence: `src/main/java/org/simdjson/SimdJsonParser.java`)
- DOM iterator → Tape builder: builds tape (evidence: `src/main/java/org/simdjson/JsonIterator.java`)
- DOM iterator → Structural indexes: reads positions (evidence: `src/main/java/org/simdjson/JsonIterator.java`)
- DOM iterator → DOM values: returns values (evidence: `src/main/java/org/simdjson/JsonIterator.java`)
- Tape builder → Value tape: appends values (evidence: `src/main/java/org/simdjson/TapeBuilder.java`)
- Tape builder → String decoder: decodes strings (evidence: `src/main/java/org/simdjson/TapeBuilder.java`)
- Tape builder → Number parser: parses numbers (evidence: `src/main/java/org/simdjson/TapeBuilder.java`)
- DOM values → Value tape: reads values (evidence: `src/main/java/org/simdjson/JsonValue.java`)
- Number parser → Exponent parser: parses exponents (evidence: `src/main/java/org/simdjson/NumberParser.java`)
- Number parser → Floating conversion: converts doubles (evidence: `src/main/java/org/simdjson/NumberParser.java`)
- Number parser → Float conversion: converts floats (evidence: `src/main/java/org/simdjson/NumberParser.java`)
- Floating conversion → Number tables: uses tables (evidence: `src/main/java/org/simdjson/DoubleParser.java`)
- Float conversion → Number tables: uses tables (evidence: `src/main/java/org/simdjson/FloatParser.java`)
- String decoder → Character utilities: decodes escapes (evidence: `src/main/java/org/simdjson/StringParser.java`)
- String decoder → Vector utilities: uses SIMD vectors (evidence: `src/main/java/org/simdjson/StringParser.java`)
- Schema iterator → Resolved schema: uses resolved schema (evidence: `src/main/java/org/simdjson/SchemaBasedJsonIterator.java`)
- Schema iterator → On-demand iterator: uses traversal (evidence: `src/main/java/org/simdjson/SchemaBasedJsonIterator.java`)
- Class resolver → Resolved schema: resolves classes (evidence: `src/main/java/org/simdjson/ClassResolver.java`)
- Resolved schema → Constructor arguments: maps parameters (evidence: `src/main/java/org/simdjson/ResolvedClass.java`)
- Number parser → Parse errors: raises parse errors (evidence: `src/main/java/org/simdjson/NumberParser.java`)
