# jqlang/jq architecture

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

- Interactive diagram: https://gitdiagram.com/jqlang/jq
- Repository: https://github.com/jqlang/jq

## Overview

jq is a command-line JSON processor: users provide JSON input and a jq filter, which the CLI compiles, evaluates, and emits as JSON output. The graph separates input handling, filter compilation, execution/built-ins, and value representation/serialization. The README establishes the product workflow; source-index references support the internal module links. Some CLI and runtime details are summarized from API boundaries because the corresponding source was not excerpted.

Main entry points: [`src/jv.c`](https://github.com/jqlang/jq/blob/master/src/jv.c) (JSON values), [`src/main.c`](https://github.com/jqlang/jq/blob/master/src/main.c) (jq CLI), [`src/compile.c`](https://github.com/jqlang/jq/blob/master/src/compile.c) (Bytecode compiler), [`src/execute.c`](https://github.com/jqlang/jq/blob/master/src/execute.c) (Filter evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and input"]
  node_cli["jq CLI<br/>[main.c]"]
  node_input["Input handling<br/>[util.c]"]
end

subgraph group_compile["Filter compilation"]
  node_lexer["Filter lexer<br/>[lexer.c]"]
  node_parser["Filter parser<br/>[parser.c]"]
  node_compiler["Bytecode compiler<br/>[compile.c]"]
  node_linker["Module linker<br/>[linker.c]"]
  node_locations["Source locations<br/>[locfile.c]"]
end

subgraph group_runtime["Evaluation runtime"]
  node_bytecode["Bytecode format<br/>[bytecode.c]"]
  node_interpreter["Filter evaluator<br/>[execute.c]"]
  node_builtins["Built-in filters<br/>[builtin.c]"]
  node_jqapi["jq runtime API<br/>[jq.h]"]
  node_datetime["Date-time filters<br/>[iso8601.c]"]
end

subgraph group_values["JSON values"]
  node_jsonparse["JSON parser<br/>[jv_parse.c]"]
  node_jv["JSON values<br/>[jv.c]"]
  node_allocation["Value allocation<br/>[jv_alloc.c]"]
  node_unicode["Unicode support<br/>[jv_unicode.c]"]
  node_numberfmt["Number conversion<br/>[jv_dtoa.c]"]
  node_jsonprint["JSON printer<br/>[jv_print.c]"]
end

node_user(("User"))

node_user -->|"runs filters"| node_cli
node_cli -->|"reads input"| node_input
node_cli -->|"uses runtime API"| node_jqapi
node_input -.->|"parses JSON"| node_jsonparse
node_parser -->|"requests tokens"| node_lexer
node_parser -->|"builds filter blocks"| node_compiler
node_compiler -->|"compiles bytecode"| node_bytecode
node_compiler -->|"records locations"| node_locations
node_linker -->|"binds modules"| node_compiler
node_jqapi -.->|"compiles filters"| node_parser
node_jqapi -.->|"starts evaluation"| node_interpreter
node_interpreter -->|"interprets instructions"| node_bytecode
node_interpreter -->|"dispatches functions"| node_builtins
node_builtins -->|"uses date routines"| node_datetime
node_builtins -->|"operates on values"| node_jv
node_jv -->|"allocates storage"| node_allocation
node_jv -->|"uses UTF-8 helpers"| node_unicode
node_jv -->|"converts numbers"| node_numberfmt
node_cli -.->|"writes results"| node_jsonprint
node_jsonparse -->|"creates values"| node_jv
node_jsonprint -->|"serializes values"| node_jv

click node_cli "https://github.com/jqlang/jq/blob/master/src/main.c"
click node_input "https://github.com/jqlang/jq/blob/master/src/util.c"
click node_jsonparse "https://github.com/jqlang/jq/blob/master/src/jv_parse.c"
click node_lexer "https://github.com/jqlang/jq/blob/master/src/lexer.c"
click node_parser "https://github.com/jqlang/jq/blob/master/src/parser.c"
click node_compiler "https://github.com/jqlang/jq/blob/master/src/compile.c"
click node_linker "https://github.com/jqlang/jq/blob/master/src/linker.c"
click node_bytecode "https://github.com/jqlang/jq/blob/master/src/bytecode.c"
click node_interpreter "https://github.com/jqlang/jq/blob/master/src/execute.c"
click node_builtins "https://github.com/jqlang/jq/blob/master/src/builtin.c"
click node_jqapi "https://github.com/jqlang/jq/blob/master/src/jq.h"
click node_jv "https://github.com/jqlang/jq/blob/master/src/jv.c"
click node_allocation "https://github.com/jqlang/jq/blob/master/src/jv_alloc.c"
click node_unicode "https://github.com/jqlang/jq/blob/master/src/jv_unicode.c"
click node_numberfmt "https://github.com/jqlang/jq/blob/master/src/jv_dtoa.c"
click node_jsonprint "https://github.com/jqlang/jq/blob/master/src/jv_print.c"
click node_datetime "https://github.com/jqlang/jq/blob/master/src/iso8601.c"
click node_locations "https://github.com/jqlang/jq/blob/master/src/locfile.c"

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_cli,node_input,node_user toneBlue
class node_lexer,node_parser,node_compiler,node_linker,node_locations toneAmber
class node_bytecode,node_interpreter,node_builtins,node_jqapi,node_datetime toneMint
class node_jsonparse,node_jv,node_allocation,node_unicode,node_numberfmt,node_jsonprint toneRose
```

## Components

### CLI and input

- [jq CLI](https://github.com/jqlang/jq/blob/master/src/main.c): `src/main.c`
- [Input handling](https://github.com/jqlang/jq/blob/master/src/util.c): `src/util.c`

### Filter compilation

- [Filter lexer](https://github.com/jqlang/jq/blob/master/src/lexer.c): `src/lexer.c`
- [Filter parser](https://github.com/jqlang/jq/blob/master/src/parser.c): `src/parser.c`
- [Bytecode compiler](https://github.com/jqlang/jq/blob/master/src/compile.c): `src/compile.c`
- [Module linker](https://github.com/jqlang/jq/blob/master/src/linker.c): `src/linker.c`
- [Source locations](https://github.com/jqlang/jq/blob/master/src/locfile.c): `src/locfile.c`

### Evaluation runtime

- [Bytecode format](https://github.com/jqlang/jq/blob/master/src/bytecode.c): `src/bytecode.c`
- [Filter evaluator](https://github.com/jqlang/jq/blob/master/src/execute.c): `src/execute.c`
- [Built-in filters](https://github.com/jqlang/jq/blob/master/src/builtin.c): `src/builtin.c`
- [jq runtime API](https://github.com/jqlang/jq/blob/master/src/jq.h): `src/jq.h`
- [Date-time filters](https://github.com/jqlang/jq/blob/master/src/iso8601.c): `src/iso8601.c`

### JSON values

- [JSON parser](https://github.com/jqlang/jq/blob/master/src/jv_parse.c): `src/jv_parse.c`
- [JSON values](https://github.com/jqlang/jq/blob/master/src/jv.c): `src/jv.c`
- [Value allocation](https://github.com/jqlang/jq/blob/master/src/jv_alloc.c): `src/jv_alloc.c`
- [Unicode support](https://github.com/jqlang/jq/blob/master/src/jv_unicode.c): `src/jv_unicode.c`
- [Number conversion](https://github.com/jqlang/jq/blob/master/src/jv_dtoa.c): `src/jv_dtoa.c`
- [JSON printer](https://github.com/jqlang/jq/blob/master/src/jv_print.c): `src/jv_print.c`

### Other components

- **User**

## Connections

- User → jq CLI: runs filters (evidence: `README.md`)
- jq CLI → Input handling: reads input (evidence: `src/main.c`)
- jq CLI → jq runtime API: uses runtime API (evidence: `src/main.c`)
- Input handling → JSON parser: parses JSON
- Filter parser → Filter lexer: requests tokens (evidence: `src/lexer.c`)
- Filter parser → Bytecode compiler: builds filter blocks (evidence: `src/parser.c`)
- Bytecode compiler → Bytecode format: compiles bytecode (evidence: `src/compile.c`)
- Bytecode compiler → Source locations: records locations (evidence: `src/compile.c`)
- Module linker → Bytecode compiler: binds modules (evidence: `src/linker.c`)
- jq runtime API → Filter parser: compiles filters
- jq runtime API → Filter evaluator: starts evaluation (evidence: `src/execute.c`)
- Filter evaluator → Bytecode format: interprets instructions (evidence: `src/execute.c`)
- Filter evaluator → Built-in filters: dispatches functions (evidence: `src/execute.c`)
- Built-in filters → Date-time filters: uses date routines (evidence: `src/builtin.c`)
- Built-in filters → JSON values: operates on values (evidence: `src/builtin.c`)
- JSON values → Value allocation: allocates storage (evidence: `src/jv.c`)
- JSON values → Unicode support: uses UTF-8 helpers (evidence: `src/jv.c`)
- JSON values → Number conversion: converts numbers (evidence: `src/jv.c`)
- jq CLI → JSON printer: writes results
- JSON parser → JSON values: creates values (evidence: `src/jv_parse.c`)
- JSON printer → JSON values: serializes values (evidence: `src/jv_print.c`)
