# romanr92/adaptive_json5 architecture

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

- Interactive diagram: https://gitdiagram.com/romanr92/adaptive_json5
- Repository: https://github.com/romanr92/adaptive_json5

## Overview

Adaptive_JSON5 is an embedded-oriented C++ JSON5/strict-JSON parser with explicit result-based failures, caller-provided storage, and configurable resource limits. The documented workflow is to pass input to the hosted parse API, receive a document or error, then inspect values through the document interface. The map includes lexical and primitive parsing, document/value access, resource accounting, and diagnostic formatting. Internal links are limited to relationships visible in the README or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`core/src/value/value_storage.cpp`](https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/value_storage.cpp) (Document values), [`core/src/parser/parser_engine.cpp`](https://github.com/romanr92/adaptive_json5/blob/main/core/src/parser/parser_engine.cpp) (Parser engine), [`core/src/hosted/parse.cpp`](https://github.com/romanr92/adaptive_json5/blob/main/core/src/hosted/parse.cpp) (Hosted parse), [`core/src/value/value_view.cpp`](https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/value_view.cpp) (Value access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api_parse["API and parsing"]
  node_hosted_parse["Hosted parse<br/>[parse.cpp]"]
  node_parser_engine["Parser engine<br/>[parser_engine.cpp]"]
  node_primitive_parser["Primitive parser"]
  node_input_view["Input view<br/>[input.hpp]"]
  node_result_type["Result and errors<br/>[result.hpp]"]
end

subgraph group_lexing["Lexical analysis"]
  node_scalar_lexer["Scalar lexer<br/>[scalar_lexer.hpp]"]
  node_lexer_suite["JSON5 lexer"]
end

subgraph group_values["Documents and values"]
  node_document["Document values<br/>[value_storage.cpp]"]
  node_value_access["Value access<br/>[value_view.cpp]"]
  node_value_iteration["Value iteration<br/>[value_iterator.cpp]"]
  node_value_index["Value index<br/>[value_index.hpp]"]
end

subgraph group_resources["Memory and limits"]
  node_accounted_storage["Accounted storage"]
  node_owned_block["Owned blocks<br/>[owned_block.hpp]"]
  node_buffer_storage["Buffer storage"]
  node_work_budget["Work budget<br/>[work_budget.hpp]"]
end

subgraph group_support["Diagnostics and numbers"]
  node_number_conversion["Number conversion"]
  node_diagnostics["Diagnostic formatting"]
end

node_caller(("Application"))

node_caller -->|"parses input"| node_hosted_parse
node_hosted_parse -->|"accepts input"| node_input_view
node_hosted_parse -->|"returns document"| node_document
node_hosted_parse -->|"returns result"| node_result_type
node_caller -->|"reads values"| node_value_access
node_parser_engine -->|"reads input"| node_input_view
node_parser_engine -->|"uses accounting"| node_accounted_storage
node_parser_engine -->|"uses budget"| node_work_budget
node_parser_engine -->|"builds values"| node_document
node_primitive_parser -->|"uses tokens"| node_scalar_lexer
node_primitive_parser -->|"scans input"| node_input_view
node_primitive_parser -->|"constructs values"| node_document
node_document -->|"issues indices"| node_value_index
node_accounted_storage -->|"allocates blocks"| node_owned_block
node_buffer_storage -->|"uses accounting"| node_accounted_storage
node_document -->|"provides views"| node_value_access
node_value_access -->|"iterates values"| node_value_iteration
node_value_access -.->|"converts numbers"| node_number_conversion
node_caller -->|"formats errors"| node_diagnostics

click node_hosted_parse "https://github.com/romanr92/adaptive_json5/blob/main/core/src/hosted/parse.cpp"
click node_parser_engine "https://github.com/romanr92/adaptive_json5/blob/main/core/src/parser/parser_engine.cpp"
click node_primitive_parser "https://github.com/romanr92/adaptive_json5/blob/main/core/src/parser/primitive_parser.cpp"
click node_scalar_lexer "https://github.com/romanr92/adaptive_json5/blob/main/core/includes/lexer/scalar_lexer.hpp"
click node_lexer_suite "https://github.com/romanr92/adaptive_json5/tree/main/core/src/lexer"
click node_input_view "https://github.com/romanr92/adaptive_json5/blob/main/includes/adaptive_json5/input.hpp"
click node_document "https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/value_storage.cpp"
click node_value_access "https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/value_view.cpp"
click node_value_iteration "https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/value_iterator.cpp"
click node_value_index "https://github.com/romanr92/adaptive_json5/blob/main/includes/adaptive_json5/value/value_index.hpp"
click node_accounted_storage "https://github.com/romanr92/adaptive_json5/blob/main/core/src/memory/accounted_storage.cpp"
click node_owned_block "https://github.com/romanr92/adaptive_json5/blob/main/includes/adaptive_json5/memory/owned_block.hpp"
click node_buffer_storage "https://github.com/romanr92/adaptive_json5/blob/main/core/src/memory/buffer_document_storage.cpp"
click node_work_budget "https://github.com/romanr92/adaptive_json5/blob/main/core/includes/memory/work_budget.hpp"
click node_number_conversion "https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/numeric_conversion.cpp"
click node_diagnostics "https://github.com/romanr92/adaptive_json5/blob/main/core/src/diagnostics/diagnostic_format.cpp"
click node_result_type "https://github.com/romanr92/adaptive_json5/blob/main/includes/adaptive_json5/result.hpp"

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_hosted_parse,node_parser_engine,node_primitive_parser,node_input_view,node_result_type toneBlue
class node_scalar_lexer,node_lexer_suite toneAmber
class node_document,node_value_access,node_value_iteration,node_value_index toneMint
class node_accounted_storage,node_owned_block,node_buffer_storage,node_work_budget toneRose
class node_number_conversion,node_diagnostics,node_caller toneIndigo
```

## Components

### API and parsing

- [Hosted parse](https://github.com/romanr92/adaptive_json5/blob/main/core/src/hosted/parse.cpp): `core/src/hosted/parse.cpp`
- [Parser engine](https://github.com/romanr92/adaptive_json5/blob/main/core/src/parser/parser_engine.cpp): `core/src/parser/parser_engine.cpp`
- [Primitive parser](https://github.com/romanr92/adaptive_json5/blob/main/core/src/parser/primitive_parser.cpp): `core/src/parser/primitive_parser.cpp`
- [Input view](https://github.com/romanr92/adaptive_json5/blob/main/includes/adaptive_json5/input.hpp): `includes/adaptive_json5/input.hpp`
- [Result and errors](https://github.com/romanr92/adaptive_json5/blob/main/includes/adaptive_json5/result.hpp): `includes/adaptive_json5/result.hpp`

### Lexical analysis

- [Scalar lexer](https://github.com/romanr92/adaptive_json5/blob/main/core/includes/lexer/scalar_lexer.hpp): `core/includes/lexer/scalar_lexer.hpp`
- [JSON5 lexer](https://github.com/romanr92/adaptive_json5/tree/main/core/src/lexer): `core/src/lexer`

### Documents and values

- [Document values](https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/value_storage.cpp): `core/src/value/value_storage.cpp`
- [Value access](https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/value_view.cpp): `core/src/value/value_view.cpp`
- [Value iteration](https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/value_iterator.cpp): `core/src/value/value_iterator.cpp`
- [Value index](https://github.com/romanr92/adaptive_json5/blob/main/includes/adaptive_json5/value/value_index.hpp): `includes/adaptive_json5/value/value_index.hpp`

### Memory and limits

- [Accounted storage](https://github.com/romanr92/adaptive_json5/blob/main/core/src/memory/accounted_storage.cpp): `core/src/memory/accounted_storage.cpp`
- [Owned blocks](https://github.com/romanr92/adaptive_json5/blob/main/includes/adaptive_json5/memory/owned_block.hpp): `includes/adaptive_json5/memory/owned_block.hpp`
- [Buffer storage](https://github.com/romanr92/adaptive_json5/blob/main/core/src/memory/buffer_document_storage.cpp): `core/src/memory/buffer_document_storage.cpp`
- [Work budget](https://github.com/romanr92/adaptive_json5/blob/main/core/includes/memory/work_budget.hpp): `core/includes/memory/work_budget.hpp`

### Diagnostics and numbers

- [Number conversion](https://github.com/romanr92/adaptive_json5/blob/main/core/src/value/numeric_conversion.cpp): `core/src/value/numeric_conversion.cpp`
- [Diagnostic formatting](https://github.com/romanr92/adaptive_json5/blob/main/core/src/diagnostics/diagnostic_format.cpp): `core/src/diagnostics/diagnostic_format.cpp`

### Other components

- **Application**

## Connections

- Application → Hosted parse: parses input (evidence: `README.md`)
- Hosted parse → Input view: accepts input
- Hosted parse → Document values: returns document (evidence: `README.md`)
- Hosted parse → Result and errors: returns result
- Application → Value access: reads values (evidence: `README.md`)
- Parser engine → Input view: reads input (evidence: `core/src/parser/parser_engine.cpp`)
- Parser engine → Accounted storage: uses accounting (evidence: `core/src/parser/parser_engine.cpp`)
- Parser engine → Work budget: uses budget (evidence: `core/src/parser/parser_engine.cpp`)
- Parser engine → Document values: builds values (evidence: `core/src/parser/parser_engine.cpp`)
- Primitive parser → Scalar lexer: uses tokens (evidence: `core/src/parser/primitive_parser.cpp`)
- Primitive parser → Input view: scans input (evidence: `core/src/parser/primitive_parser.cpp`)
- Primitive parser → Document values: constructs values (evidence: `core/src/parser/primitive_parser.cpp`)
- Document values → Value index: issues indices (evidence: `core/src/value/value_storage.cpp`)
- Accounted storage → Owned blocks: allocates blocks (evidence: `core/src/memory/accounted_storage.cpp`)
- Buffer storage → Accounted storage: uses accounting (evidence: `core/src/memory/buffer_document_storage.cpp`)
- Document values → Value access: provides views
- Value access → Value iteration: iterates values
- Value access → Number conversion: converts numbers
- Application → Diagnostic formatting: formats errors (evidence: `README.md`)
