# kashifrazzaqui/json-streamer architecture

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

- Interactive diagram: https://gitdiagram.com/kashifrazzaqui/json-streamer
- Repository: https://github.com/kashifrazzaqui/json-streamer

## Overview

jsonstreamer is a Python library for incrementally parsing JSON and emitting SAX-like events, with an ObjectStreamer option that collects root-level objects or arrays into entities. The main path is caller input → JSONStreamer → YAJL callbacks → events delivered to listeners; ObjectStreamer listens to those events and emits root entities. Tape buffers input, while the CFFI layer binds the native YAJL parser. The README also documents a stdin command-line mode. Relationships are limited to those visible in excerpts or explicitly documented; unsampled implementation details are not inferred.

Main entry points: [`jsonstreamer/jsonstreamer.py`](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/jsonstreamer.py) (JSONStreamer), [`jsonstreamer/yajl/parse.py`](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/yajl/parse.py) (YAJL Parser), [`jsonstreamer/events.py`](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/events.py) (Event Dispatch), [`jsonstreamer/yajl/yajl_cffi.py`](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/yajl/yajl_cffi.py) (CFFI Binding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Streaming APIs"]
  node_json_streamer["JSONStreamer<br/>[jsonstreamer.py]"]
  node_object_streamer["ObjectStreamer<br/>[jsonstreamer.py]"]
  node_cli["CLI Runner<br/>[jsonstreamer.py]"]
end

subgraph group_runtime["Parser Runtime"]
  node_events["Event Dispatch<br/>[events.py]"]
  node_tape["Input Tape<br/>[tape.py]"]
  node_yajl_parser["YAJL Parser<br/>[parse.py]"]
end

subgraph group_native["YAJL Binding"]
  node_cffi_binding["CFFI Binding<br/>[yajl_cffi.py]"]
end

node_caller(("Application"))
node_input["JSON Chunks"]
node_yajl["YAJL Library"]
node_listeners(("Event Listeners"))

node_caller -->|"feeds chunks"| node_json_streamer
node_json_streamer -->|"creates buffer"| node_tape
node_json_streamer -->|"creates parser"| node_yajl_parser
node_yajl_parser -->|"calls YAJL"| node_cffi_binding
node_cffi_binding -->|"loads library"| node_yajl
node_yajl_parser -->|"dispatches callbacks"| node_json_streamer
node_json_streamer -->|"fires events"| node_events
node_caller -->|"selects API"| node_object_streamer
node_object_streamer -->|"wraps parser"| node_json_streamer
node_object_streamer -->|"emits entities"| node_listeners
node_caller -->|"registers handlers"| node_listeners
node_events -->|"fires handlers"| node_listeners
node_caller -->|"runs command"| node_cli

click node_json_streamer "https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/jsonstreamer.py"
click node_object_streamer "https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/jsonstreamer.py"
click node_events "https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/events.py"
click node_tape "https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/tape.py"
click node_yajl_parser "https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/yajl/parse.py"
click node_cffi_binding "https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/yajl/yajl_cffi.py"
click node_cli "https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/jsonstreamer.py"

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_json_streamer,node_object_streamer,node_cli toneBlue
class node_events,node_tape,node_yajl_parser toneAmber
class node_cffi_binding toneMint
class node_caller,node_input,node_yajl,node_listeners toneIndigo
```

## Components

### Streaming APIs

- [JSONStreamer](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/jsonstreamer.py): `jsonstreamer/jsonstreamer.py`
- [ObjectStreamer](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/jsonstreamer.py): `jsonstreamer/jsonstreamer.py`
- [CLI Runner](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/jsonstreamer.py): `jsonstreamer/jsonstreamer.py`

### Parser Runtime

- [Event Dispatch](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/events.py): `jsonstreamer/events.py`
- [Input Tape](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/tape.py): `jsonstreamer/tape.py`
- [YAJL Parser](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/yajl/parse.py): `jsonstreamer/yajl/parse.py`

### YAJL Binding

- [CFFI Binding](https://github.com/kashifrazzaqui/json-streamer/blob/master/jsonstreamer/yajl/yajl_cffi.py): `jsonstreamer/yajl/yajl_cffi.py`

### Other components

- **Application**
- **JSON Chunks**
- **YAJL Library**
- **Event Listeners**

## Connections

- Application → JSONStreamer: feeds chunks (evidence: `README.md`)
- JSONStreamer → Input Tape: creates buffer (evidence: `jsonstreamer/jsonstreamer.py`)
- JSONStreamer → YAJL Parser: creates parser (evidence: `jsonstreamer/jsonstreamer.py`)
- YAJL Parser → CFFI Binding: calls YAJL (evidence: `jsonstreamer/yajl/parse.py`)
- CFFI Binding → YAJL Library: loads library (evidence: `jsonstreamer/yajl/yajl_cffi.py`)
- YAJL Parser → JSONStreamer: dispatches callbacks (evidence: `jsonstreamer/yajl/parse.py`)
- JSONStreamer → Event Dispatch: fires events (evidence: `jsonstreamer/jsonstreamer.py`)
- Application → ObjectStreamer: selects API (evidence: `README.md`)
- ObjectStreamer → JSONStreamer: wraps parser (evidence: `jsonstreamer/jsonstreamer.py`)
- ObjectStreamer → Event Listeners: emits entities (evidence: `README.md`)
- Application → Event Listeners: registers handlers (evidence: `README.md`)
- Event Dispatch → Event Listeners: fires handlers (evidence: `jsonstreamer/events.py`)
- Application → CLI Runner: runs command (evidence: `README.md`)
