# ohler55/oj architecture

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

- Interactive diagram: https://gitdiagram.com/ohler55/oj
- Repository: https://github.com/ohler55/oj

## Overview

Oj is a Ruby gem providing fast JSON parsing and Ruby-object marshalling. The main workflow accepts Ruby values or JSON input through the extension, applies mode-specific parsing or serialization, and returns Ruby objects or JSON output. It also offers an event-driven callback parser, a newer configurable parser, and compatibility behavior for the JSON gem and Rails/ActiveSupport. The graph follows documented modes and sampled dispatch code; some subsystem links use directory-level paths because their wiring was not shown in the excerpts.

Main entry points: [`ext/oj/oj.c`](https://github.com/ohler55/oj/blob/develop/ext/oj/oj.c) (Mode dispatch), [`lib/oj/json.rb`](https://github.com/ohler55/oj/blob/develop/lib/oj/json.rb) (JSON shim), [`lib/oj.rb`](https://github.com/ohler55/oj/blob/develop/lib/oj.rb) (Oj Ruby API), [`ext/oj/parse.c`](https://github.com/ohler55/oj/blob/develop/ext/oj/parse.c) (Legacy parsers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Ruby interfaces"]
  node_ruby_api["Oj Ruby API<br/>[oj.rb]"]
  node_extension["Native extension<br/>[oj.c]"]
  node_mode_dispatch["Mode dispatch<br/>[oj.c]"]
  node_ruby_result["Ruby result"]
end

subgraph group_parse["Parsing"]
  node_legacy_parse["Legacy parsers<br/>[parse.c]"]
  node_strict_parse["Strict parser<br/>[strict.c]"]
  node_compat_parse["Compat parser<br/>[compat.c]"]
  node_custom_parse["Custom parser<br/>[custom.c]"]
  node_object_parse["Object parser<br/>[object.c]"]
  node_wab_parse["WAB parser<br/>[wab.c]"]
  node_fast_parser["Fast parser<br/>[parser.c]"]
  node_callback_parse["Callback parsing<br/>[scp.c]"]
  node_saj_parse["SAJ parsing<br/>[saj.c]"]
end

subgraph group_marshal["Marshalling"]
  node_dump_dispatch["Dump dispatch<br/>[oj.c]"]
  node_dump_engine["Dump engine<br/>[dump.c]"]
  node_mode_dump["Mode serializers"]
  node_stream_output["Stream output<br/>[stream_writer.c]"]
end

subgraph group_compat["Compatibility"]
  node_json_shim["JSON shim<br/>[json.rb]"]
  node_rails_support["Rails support<br/>[rails.c]"]
  node_mimic_support["Mimic behavior<br/>[mimic.rb]"]
  node_generator_state["Generator state<br/>[state.rb]"]
end

node_caller(("Ruby caller"))

node_caller -->|"calls"| node_ruby_api
node_ruby_api -->|"loads"| node_extension
node_extension -->|"dispatches"| node_mode_dispatch
node_mode_dispatch -->|"parses legacy"| node_legacy_parse
node_mode_dispatch -->|"selects strict"| node_strict_parse
node_mode_dispatch -->|"selects compat"| node_compat_parse
node_mode_dispatch -->|"selects custom"| node_custom_parse
node_mode_dispatch -->|"selects object"| node_object_parse
node_mode_dispatch -->|"selects WAB"| node_wab_parse
node_caller -->|"uses parser"| node_fast_parser
node_caller -->|"requests callbacks"| node_callback_parse
node_caller -->|"requests SAJ"| node_saj_parse
node_legacy_parse -->|"returns"| node_ruby_result
node_fast_parser -->|"returns"| node_ruby_result
node_callback_parse -->|"emits values"| node_ruby_result
node_saj_parse -->|"emits events"| node_ruby_result
node_caller -->|"dumps value"| node_dump_dispatch
node_dump_dispatch -->|"serializes"| node_dump_engine
node_dump_dispatch -->|"selects mode"| node_mode_dump
node_dump_engine -->|"writes output"| node_stream_output
node_dump_dispatch -.->|"uses Rails mode"| node_rails_support
node_caller -->|"uses JSON API"| node_json_shim
node_json_shim -->|"configures state"| node_generator_state
node_json_shim -->|"applies mimic"| node_mimic_support
node_mimic_support -->|"provides compatibility"| node_caller

click node_ruby_api "https://github.com/ohler55/oj/blob/develop/lib/oj.rb"
click node_extension "https://github.com/ohler55/oj/blob/develop/ext/oj/oj.c"
click node_mode_dispatch "https://github.com/ohler55/oj/blob/develop/ext/oj/oj.c"
click node_legacy_parse "https://github.com/ohler55/oj/blob/develop/ext/oj/parse.c"
click node_strict_parse "https://github.com/ohler55/oj/blob/develop/ext/oj/strict.c"
click node_compat_parse "https://github.com/ohler55/oj/blob/develop/ext/oj/compat.c"
click node_custom_parse "https://github.com/ohler55/oj/blob/develop/ext/oj/custom.c"
click node_object_parse "https://github.com/ohler55/oj/blob/develop/ext/oj/object.c"
click node_wab_parse "https://github.com/ohler55/oj/blob/develop/ext/oj/wab.c"
click node_fast_parser "https://github.com/ohler55/oj/blob/develop/ext/oj/parser.c"
click node_callback_parse "https://github.com/ohler55/oj/blob/develop/ext/oj/scp.c"
click node_saj_parse "https://github.com/ohler55/oj/blob/develop/ext/oj/saj.c"
click node_dump_dispatch "https://github.com/ohler55/oj/blob/develop/ext/oj/oj.c"
click node_dump_engine "https://github.com/ohler55/oj/blob/develop/ext/oj/dump.c"
click node_mode_dump "https://github.com/ohler55/oj/tree/develop/ext/oj"
click node_stream_output "https://github.com/ohler55/oj/blob/develop/ext/oj/stream_writer.c"
click node_json_shim "https://github.com/ohler55/oj/blob/develop/lib/oj/json.rb"
click node_rails_support "https://github.com/ohler55/oj/blob/develop/ext/oj/rails.c"
click node_mimic_support "https://github.com/ohler55/oj/blob/develop/lib/oj/mimic.rb"
click node_generator_state "https://github.com/ohler55/oj/blob/develop/lib/oj/state.rb"

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_ruby_api,node_extension,node_mode_dispatch,node_ruby_result toneBlue
class node_legacy_parse,node_strict_parse,node_compat_parse,node_custom_parse,node_object_parse,node_wab_parse,node_fast_parser,node_callback_parse,node_saj_parse toneAmber
class node_dump_dispatch,node_dump_engine,node_mode_dump,node_stream_output toneMint
class node_json_shim,node_rails_support,node_mimic_support,node_generator_state toneRose
class node_caller toneIndigo
```

## Components

### Ruby interfaces

- [Oj Ruby API](https://github.com/ohler55/oj/blob/develop/lib/oj.rb): `lib/oj.rb`
- [Native extension](https://github.com/ohler55/oj/blob/develop/ext/oj/oj.c): `ext/oj/oj.c`
- [Mode dispatch](https://github.com/ohler55/oj/blob/develop/ext/oj/oj.c): `ext/oj/oj.c`
- **Ruby result**

### Parsing

- [Legacy parsers](https://github.com/ohler55/oj/blob/develop/ext/oj/parse.c): `ext/oj/parse.c`
- [Strict parser](https://github.com/ohler55/oj/blob/develop/ext/oj/strict.c): `ext/oj/strict.c`
- [Compat parser](https://github.com/ohler55/oj/blob/develop/ext/oj/compat.c): `ext/oj/compat.c`
- [Custom parser](https://github.com/ohler55/oj/blob/develop/ext/oj/custom.c): `ext/oj/custom.c`
- [Object parser](https://github.com/ohler55/oj/blob/develop/ext/oj/object.c): `ext/oj/object.c`
- [WAB parser](https://github.com/ohler55/oj/blob/develop/ext/oj/wab.c): `ext/oj/wab.c`
- [Fast parser](https://github.com/ohler55/oj/blob/develop/ext/oj/parser.c): `ext/oj/parser.c`
- [Callback parsing](https://github.com/ohler55/oj/blob/develop/ext/oj/scp.c): `ext/oj/scp.c`
- [SAJ parsing](https://github.com/ohler55/oj/blob/develop/ext/oj/saj.c): `ext/oj/saj.c`

### Marshalling

- [Dump dispatch](https://github.com/ohler55/oj/blob/develop/ext/oj/oj.c): `ext/oj/oj.c`
- [Dump engine](https://github.com/ohler55/oj/blob/develop/ext/oj/dump.c): `ext/oj/dump.c`
- [Mode serializers](https://github.com/ohler55/oj/tree/develop/ext/oj): `ext/oj`
- [Stream output](https://github.com/ohler55/oj/blob/develop/ext/oj/stream_writer.c): `ext/oj/stream_writer.c`

### Compatibility

- [JSON shim](https://github.com/ohler55/oj/blob/develop/lib/oj/json.rb): `lib/oj/json.rb`
- [Rails support](https://github.com/ohler55/oj/blob/develop/ext/oj/rails.c): `ext/oj/rails.c`
- [Mimic behavior](https://github.com/ohler55/oj/blob/develop/lib/oj/mimic.rb): `lib/oj/mimic.rb`
- [Generator state](https://github.com/ohler55/oj/blob/develop/lib/oj/state.rb): `lib/oj/state.rb`

### Other components

- **Ruby caller**

## Connections

- Ruby caller → Oj Ruby API: calls
- Oj Ruby API → Native extension: loads
- Native extension → Mode dispatch: dispatches
- Mode dispatch → Legacy parsers: parses legacy
- Mode dispatch → Strict parser: selects strict
- Mode dispatch → Compat parser: selects compat
- Mode dispatch → Custom parser: selects custom
- Mode dispatch → Object parser: selects object
- Mode dispatch → WAB parser: selects WAB
- Ruby caller → Fast parser: uses parser
- Ruby caller → Callback parsing: requests callbacks
- Ruby caller → SAJ parsing: requests SAJ
- Legacy parsers → Ruby result: returns
- Fast parser → Ruby result: returns
- Callback parsing → Ruby result: emits values
- SAJ parsing → Ruby result: emits events
- Ruby caller → Dump dispatch: dumps value
- Dump dispatch → Dump engine: serializes
- Dump dispatch → Mode serializers: selects mode
- Dump engine → Stream output: writes output
- Dump dispatch → Rails support: uses Rails mode
- Ruby caller → JSON shim: uses JSON API
- JSON shim → Generator state: configures state
- JSON shim → Mimic behavior: applies mimic
- Mimic behavior → Ruby caller: provides compatibility