# serde-rs/serde architecture

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

- Interactive diagram: https://gitdiagram.com/serde-rs/serde
- Repository: https://github.com/serde-rs/serde

## Overview

#### Purpose and workspace
Serde is a Rust serialization/deserialization framework. This Cargo workspace separates stable public traits, the user-facing facade, compile-time derives, and validation. Workspace definition: `Cargo.toml`.

#### Public API facade
The `serde` crate is the normal consumer entry point. It re-exports core APIs and conditionally integrates derive support, while retaining compatibility-oriented code such as 128-bit integer handling. Primary paths: `serde/src/lib.rs`, `serde/src/core`, `serde/src/integer128.rs`.

#### Format-agnostic serialization contract
`serde_core` defines the format-independent boundary between Rust data types and external format crates: `Serialize` drives values into a format-provided `Serializer`; `Deserialize` reconstructs values through a format-provided `Deserializer` and visitors. Implementations for standard Rust types live alongside these contracts. Paths: `serde_core/src/ser/mod.rs`, `serde_core/src/de/mod.rs`, `serde_core/src/lib.rs`.

#### Value traversal and error boundary
Serialization is controlled by the data type’s `Serialize` implementation; deserialization is controlled by the format parser plus Serde’s `Visitor`/seed protocol. Formats own concrete wire representations, parsers, output buffers, and error types; Serde owns generic structural traversal and trait contracts. In-memory deserialization utilities and ignored-value support are provided in: `serde_core/src/de/value.rs`, `serde_core/src/de/ignored_any.rs`, `serde_core/src/ser/impls.rs`.

#### Derive macro compiler pipeline
`serde_derive` is a procedural-macro crate invoked by Rust compilation for `#[derive(Serialize, Deserialize)]`. It parses a struct/enum and Serde attributes into an internal AST, validates representation and attribute constraints, computes generic bounds/names, then emits trait implementations for serialization and deserialization. Entry and stages: `serde_derive/src/lib.rs`, `serde_derive/src/internals/ast.rs`, `serde_derive/src/internals/check.rs`.

#### Generated implementation strategies
Macro generation has distinct serializer and deserializer pipelines. Deserialization generation branches by container shape and enum representation—external, internal, adjacent, and untagged tags—while serialization emits corresponding structural calls into `Serializer`. Paths: `serde_derive/src/ser.rs`, `serde_derive/src/de.rs`, `serde_derive/src/de/enum_.rs`.

#### Runtime, integration, and delivery
This is a Rust library workspace, not an application or service. Consumer applications supply data-format crates (for example `serde_json`); those external crates implement Serde’s serializer/deserializer interfaces. The repository targets standard Rust and constrained/no-std environments, with a no-std integration target at `test_suite/no_std/Cargo.toml`. GitHub Actions provides CI: `.github/workflows/ci.yml`.

Main entry points: [`serde_core/src/lib.rs`](https://github.com/serde-rs/serde/blob/master/serde_core/src/lib.rs) (serde_core), [`serde/src/lib.rs`](https://github.com/serde-rs/serde/blob/master/serde/src/lib.rs) (serde facade), [`Cargo.toml`](https://github.com/serde-rs/serde/blob/master/Cargo.toml) (Cargo workspace), [`serde_derive/src/lib.rs`](https://github.com/serde-rs/serde/blob/master/serde_derive/src/lib.rs) (serde_derive)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_cargo_workspace["Cargo workspace<br/>[Cargo.toml]"]
  node_serde_facade["serde facade<br/>public crate<br/>[lib.rs]"]
  node_compat_integer128["128-bit compatibility<br/>runtime compatibility<br/>[integer128.rs]"]
end

subgraph group_runtime["Runtime contracts"]
  node_serde_core["serde_core<br/>contract crate<br/>[lib.rs]"]
  node_serialize_contract["Serialize + Serializer<br/>serialization contract<br/>[mod.rs]"]
  node_deserialize_contract["Deserialize + Deserializer<br/>deserialization contract<br/>[mod.rs]"]
  node_standard_impls["Standard type impls<br/>runtime implementations<br/>[impls.rs]"]
  node_value_utilities["In-memory values<br/>deserialization utilities<br/>[value.rs]"]
  node_ignored_any["Ignored-value support<br/>deserialization utility<br/>[ignored_any.rs]"]
end

subgraph group_derive["Derive compiler"]
  node_derive_entry{{"serde_derive<br/>procedural macro crate<br/>[lib.rs]"}}
  node_derive_ast["Attribute AST<br/>macro intermediate representation<br/>[ast.rs]"]
  node_derive_validation["Representation checks<br/>macro validation<br/>[check.rs]"]
  node_serialize_codegen["Serialize codegen<br/>macro generation<br/>[ser.rs]"]
  node_deserialize_codegen["Deserialize codegen<br/>macro generation<br/>[de.rs]"]
  node_enum_codegen["Enum decoding<br/>macro generation<br/>[enum_.rs]"]
end

subgraph group_integration["Integration"]
  node_external_formats["External format crates<br/>format implementations"]
  node_consumer_types["Consumer data types<br/>downstream Rust code"]
  node_no_std_target["no-std integration<br/>integration target<br/>[Cargo.toml]"]
  node_ci["GitHub Actions CI<br/>automation<br/>[ci.yml]"]
end

node_cargo_workspace -->|"includes"| node_serde_facade
node_cargo_workspace -->|"includes"| node_serde_core
node_cargo_workspace -->|"includes"| node_derive_entry
node_serde_facade -->|"re-exports core API"| node_serde_core
node_serde_facade -->|"retains"| node_compat_integer128
node_serde_facade -.->|"optional derive integration"| node_derive_entry
node_serde_core -->|"defines"| node_serialize_contract
node_serde_core -->|"defines"| node_deserialize_contract
node_serde_core -->|"provides"| node_standard_impls
node_serde_core -->|"provides"| node_value_utilities
node_serde_core -->|"provides"| node_ignored_any
node_derive_entry -->|"parses into"| node_derive_ast
node_derive_ast -->|"validated by"| node_derive_validation
node_derive_validation -->|"feeds"| node_serialize_codegen
node_derive_validation -->|"feeds"| node_deserialize_codegen
node_deserialize_codegen -->|"branches for enums"| node_enum_codegen
node_serialize_codegen -->|"emits impls for"| node_serialize_contract
node_deserialize_codegen -->|"emits impls for"| node_deserialize_contract
node_consumer_types -->|"derive invocation"| node_derive_entry
node_consumer_types -->|"implements or calls"| node_serialize_contract
node_consumer_types -->|"implements or calls"| node_deserialize_contract
node_external_formats -->|"implements serializer"| node_serialize_contract
node_external_formats -->|"implements deserializer"| node_deserialize_contract
node_no_std_target -.->|"validates constrained runtime"| node_serde_facade
node_ci -.->|"builds and validates"| node_cargo_workspace

click node_cargo_workspace "https://github.com/serde-rs/serde/blob/master/Cargo.toml"
click node_serde_facade "https://github.com/serde-rs/serde/blob/master/serde/src/lib.rs"
click node_compat_integer128 "https://github.com/serde-rs/serde/blob/master/serde/src/integer128.rs"
click node_serde_core "https://github.com/serde-rs/serde/blob/master/serde_core/src/lib.rs"
click node_serialize_contract "https://github.com/serde-rs/serde/blob/master/serde_core/src/ser/mod.rs"
click node_deserialize_contract "https://github.com/serde-rs/serde/blob/master/serde_core/src/de/mod.rs"
click node_standard_impls "https://github.com/serde-rs/serde/blob/master/serde_core/src/ser/impls.rs"
click node_value_utilities "https://github.com/serde-rs/serde/blob/master/serde_core/src/de/value.rs"
click node_ignored_any "https://github.com/serde-rs/serde/blob/master/serde_core/src/de/ignored_any.rs"
click node_derive_entry "https://github.com/serde-rs/serde/blob/master/serde_derive/src/lib.rs"
click node_derive_ast "https://github.com/serde-rs/serde/blob/master/serde_derive/src/internals/ast.rs"
click node_derive_validation "https://github.com/serde-rs/serde/blob/master/serde_derive/src/internals/check.rs"
click node_serialize_codegen "https://github.com/serde-rs/serde/blob/master/serde_derive/src/ser.rs"
click node_deserialize_codegen "https://github.com/serde-rs/serde/blob/master/serde_derive/src/de.rs"
click node_enum_codegen "https://github.com/serde-rs/serde/blob/master/serde_derive/src/de/enum_.rs"
click node_no_std_target "https://github.com/serde-rs/serde/blob/master/test_suite/no_std/Cargo.toml"
click node_ci "https://github.com/serde-rs/serde/blob/master/.github/workflows/ci.yml"

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_cargo_workspace,node_serde_facade,node_compat_integer128 toneBlue
class node_serde_core,node_serialize_contract,node_deserialize_contract,node_standard_impls,node_value_utilities,node_ignored_any toneAmber
class node_derive_entry,node_derive_ast,node_derive_validation,node_serialize_codegen,node_deserialize_codegen,node_enum_codegen toneMint
class node_external_formats,node_consumer_types,node_no_std_target,node_ci toneRose
```

## Components

### Workspace

- [Cargo workspace](https://github.com/serde-rs/serde/blob/master/Cargo.toml): workspace · Separates facade, stable contracts, and procedural macros. · `Cargo.toml`
- [serde facade](https://github.com/serde-rs/serde/blob/master/serde/src/lib.rs): public crate · Normal consumer entry point and API re-export layer. · `serde/src/lib.rs`
- [128-bit compatibility](https://github.com/serde-rs/serde/blob/master/serde/src/integer128.rs): runtime compatibility · `serde/src/integer128.rs`

### Runtime contracts

- [serde_core](https://github.com/serde-rs/serde/blob/master/serde_core/src/lib.rs): contract crate · Format-independent serialization and deserialization traits. · `serde_core/src/lib.rs`
- [Serialize + Serializer](https://github.com/serde-rs/serde/blob/master/serde_core/src/ser/mod.rs): serialization contract · Values drive structural writes into format-owned serializers. · `serde_core/src/ser/mod.rs`
- [Deserialize + Deserializer](https://github.com/serde-rs/serde/blob/master/serde_core/src/de/mod.rs): deserialization contract · Format parsers drive reconstruction through visitors and seeds. · `serde_core/src/de/mod.rs`
- [Standard type impls](https://github.com/serde-rs/serde/blob/master/serde_core/src/ser/impls.rs): runtime implementations · `serde_core/src/ser/impls.rs`
- [In-memory values](https://github.com/serde-rs/serde/blob/master/serde_core/src/de/value.rs): deserialization utilities · `serde_core/src/de/value.rs`
- [Ignored-value support](https://github.com/serde-rs/serde/blob/master/serde_core/src/de/ignored_any.rs): deserialization utility · `serde_core/src/de/ignored_any.rs`

### Derive compiler

- [serde_derive](https://github.com/serde-rs/serde/blob/master/serde_derive/src/lib.rs): procedural macro crate · Invoked by Rust compilation for Serialize and Deserialize derives. · `serde_derive/src/lib.rs`
- [Attribute AST](https://github.com/serde-rs/serde/blob/master/serde_derive/src/internals/ast.rs): macro intermediate representation · Parses structs, enums, and Serde attributes. · `serde_derive/src/internals/ast.rs`
- [Representation checks](https://github.com/serde-rs/serde/blob/master/serde_derive/src/internals/check.rs): macro validation · Validates attributes and representation constraints. · `serde_derive/src/internals/check.rs`
- [Serialize codegen](https://github.com/serde-rs/serde/blob/master/serde_derive/src/ser.rs): macro generation · Emits structural calls into Serializer. · `serde_derive/src/ser.rs`
- [Deserialize codegen](https://github.com/serde-rs/serde/blob/master/serde_derive/src/de.rs): macro generation · Generates container and enum deserialization strategies. · `serde_derive/src/de.rs`
- [Enum decoding](https://github.com/serde-rs/serde/blob/master/serde_derive/src/de/enum_.rs): macro generation · Handles external, internal, adjacent, and untagged representations. · `serde_derive/src/de/enum_.rs`

### Integration

- **External format crates**: format implementations · Own wire formats, parsers, buffers, and concrete error types.
- **Consumer data types**: downstream Rust code · Use Serde traits directly or through generated implementations.
- [no-std integration](https://github.com/serde-rs/serde/blob/master/test_suite/no_std/Cargo.toml): integration target · `test_suite/no_std/Cargo.toml`
- [GitHub Actions CI](https://github.com/serde-rs/serde/blob/master/.github/workflows/ci.yml): automation · `.github/workflows/ci.yml`

## Connections

- Cargo workspace → serde facade: includes
- Cargo workspace → serde_core: includes
- Cargo workspace → serde_derive: includes
- serde facade → serde_core: re-exports core API
- serde facade → 128-bit compatibility: retains
- serde facade → serde_derive: optional derive integration
- serde_core → Serialize + Serializer: defines
- serde_core → Deserialize + Deserializer: defines
- serde_core → Standard type impls: provides
- serde_core → In-memory values: provides
- serde_core → Ignored-value support: provides
- serde_derive → Attribute AST: parses into
- Attribute AST → Representation checks: validated by
- Representation checks → Serialize codegen: feeds
- Representation checks → Deserialize codegen: feeds
- Deserialize codegen → Enum decoding: branches for enums
- Serialize codegen → Serialize + Serializer: emits impls for
- Deserialize codegen → Deserialize + Deserializer: emits impls for
- Consumer data types → serde_derive: derive invocation
- Consumer data types → Serialize + Serializer: implements or calls
- Consumer data types → Deserialize + Deserializer: implements or calls
- External format crates → Serialize + Serializer: implements serializer
- External format crates → Deserialize + Deserializer: implements deserializer
- no-std integration → serde facade: validates constrained runtime
- GitHub Actions CI → Cargo workspace: builds and validates