# go-yaml/yaml architecture

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

- Interactive diagram: https://gitdiagram.com/go-yaml/yaml
- Repository: https://github.com/go-yaml/yaml

## Overview

This repository is a Go YAML library: callers marshal Go values to YAML or unmarshal YAML into Go values, with streaming Decoder and Encoder APIs as well. The documented workflow is represented alongside the reader, scanner, parser, resolver, node conversion, and emitter layers. Parsing and emission internals are only partially sampled, so their likely internal links are dashed and uncited; documented API usage and excerpted calls are cited where shown.

Main entry points: [`decode.go`](https://github.com/go-yaml/yaml/blob/v3/decode.go) (Go value decoder), [`encode.go`](https://github.com/go-yaml/yaml/blob/v3/encode.go) (Go value encoder), [`yaml.go`](https://github.com/go-yaml/yaml/blob/v3/yaml.go) (Marshal / Unmarshal API), [`scannerc.go`](https://github.com/go-yaml/yaml/blob/v3/scannerc.go) (Token scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["Marshal / Unmarshal API<br/>[yaml.go]"]
  node_stream["Stream APIs<br/>[yaml.go]"]
  node_nodes["Node model<br/>[yaml.go]"]
end

subgraph group_decode["Decode Pipeline"]
  node_reader["Input reader<br/>[readerc.go]"]
  node_scanner["Token scanner<br/>[scannerc.go]"]
  node_parser["Event parser<br/>[parserc.go]"]
  node_decodeconv["Go value decoder<br/>[decode.go]"]
  node_resolver["Scalar resolver<br/>[resolve.go]"]
end

subgraph group_encode["Encode Pipeline"]
  node_encoder["Go value encoder<br/>[encode.go]"]
  node_sorter["Map key sorter<br/>[sorter.go]"]
  node_emitter["YAML emitter<br/>[emitterc.go]"]
  node_writer["Output writer<br/>[writerc.go]"]
end

subgraph group_core["YAML Core"]
  node_apihelpers["Event constructors<br/>[apic.go]"]
  node_types["Token and event types<br/>[yamlh.go]"]
  node_private["Parsing primitives<br/>[yamlprivateh.go]"]
end

node_caller(("Go caller"))

node_caller -->|"calls"| node_api
node_caller -->|"uses"| node_stream
node_api -->|"decodes values"| node_decodeconv
node_api -->|"encodes values"| node_encoder
node_stream -.->|"decodes values"| node_decodeconv
node_stream -.->|"encodes values"| node_encoder
node_decodeconv -->|"sets parser input"| node_reader
node_reader -.->|"supplies characters"| node_scanner
node_scanner -.->|"provides tokens"| node_parser
node_parser -.->|"provides events"| node_decodeconv
node_decodeconv -.->|"resolves scalars"| node_resolver
node_decodeconv -.->|"builds nodes"| node_nodes
node_encoder -.->|"encodes nodes"| node_nodes
node_encoder -.->|"sorts map keys"| node_sorter
node_encoder -->|"emits events"| node_emitter
node_emitter -.->|"writes output"| node_writer
node_apihelpers -.->|"initializes emitter"| node_emitter
node_types -.->|"defines structures"| node_parser
node_private -.->|"supports scanning"| node_scanner

click node_api "https://github.com/go-yaml/yaml/blob/v3/yaml.go"
click node_stream "https://github.com/go-yaml/yaml/blob/v3/yaml.go"
click node_reader "https://github.com/go-yaml/yaml/blob/v3/readerc.go"
click node_scanner "https://github.com/go-yaml/yaml/blob/v3/scannerc.go"
click node_parser "https://github.com/go-yaml/yaml/blob/v3/parserc.go"
click node_decodeconv "https://github.com/go-yaml/yaml/blob/v3/decode.go"
click node_resolver "https://github.com/go-yaml/yaml/blob/v3/resolve.go"
click node_nodes "https://github.com/go-yaml/yaml/blob/v3/yaml.go"
click node_encoder "https://github.com/go-yaml/yaml/blob/v3/encode.go"
click node_sorter "https://github.com/go-yaml/yaml/blob/v3/sorter.go"
click node_emitter "https://github.com/go-yaml/yaml/blob/v3/emitterc.go"
click node_writer "https://github.com/go-yaml/yaml/blob/v3/writerc.go"
click node_apihelpers "https://github.com/go-yaml/yaml/blob/v3/apic.go"
click node_types "https://github.com/go-yaml/yaml/blob/v3/yamlh.go"
click node_private "https://github.com/go-yaml/yaml/blob/v3/yamlprivateh.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_stream,node_nodes toneBlue
class node_reader,node_scanner,node_parser,node_decodeconv,node_resolver toneAmber
class node_encoder,node_sorter,node_emitter,node_writer toneMint
class node_apihelpers,node_types,node_private toneRose
class node_caller toneIndigo
```

## Components

### Public API

- [Marshal / Unmarshal API](https://github.com/go-yaml/yaml/blob/v3/yaml.go): `yaml.go`
- [Stream APIs](https://github.com/go-yaml/yaml/blob/v3/yaml.go): `yaml.go`
- [Node model](https://github.com/go-yaml/yaml/blob/v3/yaml.go): `yaml.go`

### Decode Pipeline

- [Input reader](https://github.com/go-yaml/yaml/blob/v3/readerc.go): `readerc.go`
- [Token scanner](https://github.com/go-yaml/yaml/blob/v3/scannerc.go): `scannerc.go`
- [Event parser](https://github.com/go-yaml/yaml/blob/v3/parserc.go): `parserc.go`
- [Go value decoder](https://github.com/go-yaml/yaml/blob/v3/decode.go): `decode.go`
- [Scalar resolver](https://github.com/go-yaml/yaml/blob/v3/resolve.go): `resolve.go`

### Encode Pipeline

- [Go value encoder](https://github.com/go-yaml/yaml/blob/v3/encode.go): `encode.go`
- [Map key sorter](https://github.com/go-yaml/yaml/blob/v3/sorter.go): `sorter.go`
- [YAML emitter](https://github.com/go-yaml/yaml/blob/v3/emitterc.go): `emitterc.go`
- [Output writer](https://github.com/go-yaml/yaml/blob/v3/writerc.go): `writerc.go`

### YAML Core

- [Event constructors](https://github.com/go-yaml/yaml/blob/v3/apic.go): `apic.go`
- [Token and event types](https://github.com/go-yaml/yaml/blob/v3/yamlh.go): `yamlh.go`
- [Parsing primitives](https://github.com/go-yaml/yaml/blob/v3/yamlprivateh.go): `yamlprivateh.go`

### Other components

- **Go caller**

## Connections

- Go caller → Marshal / Unmarshal API: calls (evidence: `README.md`)
- Go caller → Stream APIs: uses (evidence: `README.md`)
- Marshal / Unmarshal API → Go value decoder: decodes values (evidence: `README.md`)
- Marshal / Unmarshal API → Go value encoder: encodes values (evidence: `README.md`)
- Stream APIs → Go value decoder: decodes values
- Stream APIs → Go value encoder: encodes values
- Go value decoder → Input reader: sets parser input (evidence: `decode.go`)
- Input reader → Token scanner: supplies characters
- Token scanner → Event parser: provides tokens
- Event parser → Go value decoder: provides events
- Go value decoder → Scalar resolver: resolves scalars
- Go value decoder → Node model: builds nodes
- Go value encoder → Node model: encodes nodes
- Go value encoder → Map key sorter: sorts map keys
- Go value encoder → YAML emitter: emits events (evidence: `encode.go`)
- YAML emitter → Output writer: writes output
- Event constructors → YAML emitter: initializes emitter
- Token and event types → Event parser: defines structures
- Parsing primitives → Token scanner: supports scanning
