# bytedance/sonic architecture

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

- Interactive diagram: https://gitdiagram.com/bytedance/sonic
- Repository: https://github.com/bytedance/sonic

## Overview

Sonic is a high-performance Go JSON library. The principal workflow is a caller submitting a Go value or JSON input to the public API, which serializes or deserializes it; callers can also parse, inspect, search, and manipulate JSON values through the AST APIs. The implementation includes runtime encoder compilation, multiple decoder paths, and architecture-specific native acceleration. Edges are limited to relationships visible in the excerpts, SOURCE INDEX references, or README; several implementation links remain uncertain because their source was not sampled.

Main entry points: [`encoder/encoder_native.go`](https://github.com/bytedance/sonic/blob/main/encoder/encoder_native.go) (Encoder API), [`decoder/decoder_native.go`](https://github.com/bytedance/sonic/blob/main/decoder/decoder_native.go) (Decoder API), [`internal/encoder/compiler.go`](https://github.com/bytedance/sonic/blob/main/internal/encoder/compiler.go) (Encode Compiler), [`internal/decoder/jitdec/assembler_regabi_amd64.go`](https://github.com/bytedance/sonic/blob/main/internal/decoder/jitdec/assembler_regabi_amd64.go) (JIT Decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public APIs"]
  node_api["JSON API<br/>[api.go]"]
  node_decoder["Decoder API<br/>[decoder_native.go]"]
  node_encoder["Encoder API<br/>[encoder_native.go]"]
  node_compat["Compatibility Fallbacks<br/>[decoder_compat.go]"]
  node_options["Encoding Options<br/>[option.go]"]
end

subgraph group_ast["JSON Value APIs"]
  node_astnode["JSON Nodes<br/>[node.go]"]
  node_parser["JSON Parser<br/>[parser.go]"]
  node_search["Path Search<br/>[search.go]"]
end

subgraph group_runtime["Runtime Binding"]
  node_compiler["Encode Compiler<br/>[compiler.go]"]
  node_encodeasm["Encode Assembler"]
  node_resolver["Field Resolver<br/>[fields.go]"]
  node_jitdecode["JIT Decoder"]
  node_optdecode["Optimized Decoder<br/>[node.go]"]
  node_jit["JIT Runtime<br/>[assembler_amd64.go]"]
  node_loader["Code Loader<br/>[loader.go]"]
end

subgraph group_accel["Native Acceleration"]
  node_nativeapi["Native Dispatch<br/>[dispatch_amd64.go]"]
  node_nativec["SIMD Primitives<br/>[scanning.h]"]
end

node_caller(("Go caller"))

node_caller -->|"uses JSON"| node_api
node_api -->|"uses AST"| node_astnode
node_caller -->|"encodes values"| node_encoder
node_caller -->|"decodes JSON"| node_decoder
node_caller -->|"manipulates values"| node_astnode
node_parser -.->|"parses values"| node_astnode
node_search -.->|"searches input"| node_parser
node_encoder -.->|"compiles encoding"| node_compiler
node_compiler -->|"resolves fields"| node_resolver
node_compiler -.->|"builds program"| node_encodeasm
node_encodeasm -->|"uses JIT"| node_jit
node_jitdecode -->|"uses JIT"| node_jit
node_jitdecode -->|"calls native"| node_nativeapi
node_nativeapi -.->|"dispatches primitives"| node_nativec
node_jit -->|"assembles code"| node_loader
node_decoder -.->|"binds at runtime"| node_jitdecode
node_decoder -.->|"uses optimized path"| node_optdecode
node_encoder -.->|"fallbacks available"| node_compat
node_encoder -->|"accepts options"| node_options

click node_api "https://github.com/bytedance/sonic/blob/main/api.go"
click node_decoder "https://github.com/bytedance/sonic/blob/main/decoder/decoder_native.go"
click node_encoder "https://github.com/bytedance/sonic/blob/main/encoder/encoder_native.go"
click node_astnode "https://github.com/bytedance/sonic/blob/main/ast/node.go"
click node_parser "https://github.com/bytedance/sonic/blob/main/ast/parser.go"
click node_search "https://github.com/bytedance/sonic/blob/main/ast/search.go"
click node_compiler "https://github.com/bytedance/sonic/blob/main/internal/encoder/compiler.go"
click node_encodeasm "https://github.com/bytedance/sonic/blob/main/internal/encoder/x86/assembler_regabi_amd64.go"
click node_resolver "https://github.com/bytedance/sonic/blob/main/internal/resolver/fields.go"
click node_jitdecode "https://github.com/bytedance/sonic/blob/main/internal/decoder/jitdec/assembler_regabi_amd64.go"
click node_optdecode "https://github.com/bytedance/sonic/blob/main/internal/decoder/optdec/node.go"
click node_jit "https://github.com/bytedance/sonic/blob/main/internal/jit/assembler_amd64.go"
click node_loader "https://github.com/bytedance/sonic/blob/main/loader/loader.go"
click node_nativeapi "https://github.com/bytedance/sonic/blob/main/internal/native/dispatch_amd64.go"
click node_nativec "https://github.com/bytedance/sonic/blob/main/native/scanning.h"
click node_compat "https://github.com/bytedance/sonic/blob/main/decoder/decoder_compat.go"
click node_options "https://github.com/bytedance/sonic/blob/main/option/option.go"

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_api,node_decoder,node_encoder,node_compat,node_options toneBlue
class node_astnode,node_parser,node_search toneAmber
class node_compiler,node_encodeasm,node_resolver,node_jitdecode,node_optdecode,node_jit,node_loader toneMint
class node_nativeapi,node_nativec toneRose
class node_caller toneIndigo
```

## Components

### Public APIs

- [JSON API](https://github.com/bytedance/sonic/blob/main/api.go): `api.go`
- [Decoder API](https://github.com/bytedance/sonic/blob/main/decoder/decoder_native.go): `decoder/decoder_native.go`
- [Encoder API](https://github.com/bytedance/sonic/blob/main/encoder/encoder_native.go): `encoder/encoder_native.go`
- [Compatibility Fallbacks](https://github.com/bytedance/sonic/blob/main/decoder/decoder_compat.go): `decoder/decoder_compat.go`
- [Encoding Options](https://github.com/bytedance/sonic/blob/main/option/option.go): `option/option.go`

### JSON Value APIs

- [JSON Nodes](https://github.com/bytedance/sonic/blob/main/ast/node.go): `ast/node.go`
- [JSON Parser](https://github.com/bytedance/sonic/blob/main/ast/parser.go): `ast/parser.go`
- [Path Search](https://github.com/bytedance/sonic/blob/main/ast/search.go): `ast/search.go`

### Runtime Binding

- [Encode Compiler](https://github.com/bytedance/sonic/blob/main/internal/encoder/compiler.go): `internal/encoder/compiler.go`
- [Encode Assembler](https://github.com/bytedance/sonic/blob/main/internal/encoder/x86/assembler_regabi_amd64.go): `internal/encoder/x86/assembler_regabi_amd64.go`
- [Field Resolver](https://github.com/bytedance/sonic/blob/main/internal/resolver/fields.go): `internal/resolver/fields.go`
- [JIT Decoder](https://github.com/bytedance/sonic/blob/main/internal/decoder/jitdec/assembler_regabi_amd64.go): `internal/decoder/jitdec/assembler_regabi_amd64.go`
- [Optimized Decoder](https://github.com/bytedance/sonic/blob/main/internal/decoder/optdec/node.go): `internal/decoder/optdec/node.go`
- [JIT Runtime](https://github.com/bytedance/sonic/blob/main/internal/jit/assembler_amd64.go): `internal/jit/assembler_amd64.go`
- [Code Loader](https://github.com/bytedance/sonic/blob/main/loader/loader.go): `loader/loader.go`

### Native Acceleration

- [Native Dispatch](https://github.com/bytedance/sonic/blob/main/internal/native/dispatch_amd64.go): `internal/native/dispatch_amd64.go`
- [SIMD Primitives](https://github.com/bytedance/sonic/blob/main/native/scanning.h): `native/scanning.h`

### Other components

- **Go caller**

## Connections

- Go caller → JSON API: uses JSON (evidence: `README.md`)
- JSON API → JSON Nodes: uses AST (evidence: `api.go`)
- Go caller → Encoder API: encodes values (evidence: `README.md`)
- Go caller → Decoder API: decodes JSON (evidence: `README.md`)
- Go caller → JSON Nodes: manipulates values (evidence: `README.md`)
- JSON Parser → JSON Nodes: parses values
- Path Search → JSON Parser: searches input
- Encoder API → Encode Compiler: compiles encoding
- Encode Compiler → Field Resolver: resolves fields (evidence: `internal/encoder/compiler.go`)
- Encode Compiler → Encode Assembler: builds program
- Encode Assembler → JIT Runtime: uses JIT (evidence: `internal/encoder/x86/assembler_regabi_amd64.go`)
- JIT Decoder → JIT Runtime: uses JIT (evidence: `internal/decoder/jitdec/assembler_regabi_amd64.go`)
- JIT Decoder → Native Dispatch: calls native (evidence: `internal/decoder/jitdec/assembler_regabi_amd64.go`)
- Native Dispatch → SIMD Primitives: dispatches primitives
- JIT Runtime → Code Loader: assembles code (evidence: `internal/jit/assembler_amd64.go`)
- Decoder API → JIT Decoder: binds at runtime
- Decoder API → Optimized Decoder: uses optimized path
- Encoder API → Compatibility Fallbacks: fallbacks available
- Encoder API → Encoding Options: accepts options
