# google/gson architecture

> Architecture diagram of the GitHub repository google/gson, 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/google/gson
- Repository: https://github.com/google/gson

## Overview

Gson is a Java library for converting Java objects to JSON and JSON to Java objects, including generic and pre-existing types. The main workflow is for an application to configure a Gson instance, then serialize or deserialize through type adapters and JSON streams; callers can also parse JSON into a tree. The graph includes the documented customization and generic-type capabilities, plus notable adapter extensions in the tree. Source excerpts show key API and parser calls; several adapter internals are unsampled, so their links are omitted rather than inferred.

Main entry points: [`gson/src/main/java/com/google/gson/TypeAdapter.java`](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/TypeAdapter.java) (TypeAdapter), [`gson/src/main/java/com/google/gson/Gson.java`](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/Gson.java) (Gson), [`gson/src/main/java/com/google/gson/stream/JsonReader.java`](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/stream/JsonReader.java) (JsonReader), [`gson/src/main/java/com/google/gson/internal/Streams.java`](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/internal/Streams.java) (Tree stream bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_builder["GsonBuilder<br/>[GsonBuilder.java]"]
  node_gson["Gson<br/>[Gson.java]"]
  node_type_token["TypeToken<br/>[TypeToken.java]"]
  node_tree_api["JSON tree API<br/>[JsonElement.java]"]
end

subgraph group_conversion["Conversion Engine"]
  node_type_adapter["TypeAdapter<br/>[TypeAdapter.java]"]
  node_adapter_factory["Adapter factories"]
  node_reflective_adapter["Reflective mapping"]
  node_collection_adapter["Collection mapping"]
  node_built_in_adapters["Built-in adapters<br/>[TypeAdapters.java]"]
end

subgraph group_streaming["JSON Processing"]
  node_json_parser["JSON parser<br/>[JsonParser.java]"]
  node_json_stream_parser["Stream parser"]
  node_streams["Tree stream bridge<br/>[Streams.java]"]
  node_json_reader["JsonReader<br/>[JsonReader.java]"]
  node_json_writer["JsonWriter<br/>[JsonWriter.java]"]
end

subgraph group_extensions["Adapter Extensions"]
  node_runtime_adapter["Runtime type adapter"]
  node_utc_adapter["UTC date adapter"]
  node_proto_adapter["Protocol Buffers adapters"]
  node_legacy_proto["Legacy proto adapter"]
end

node_application(("Java application"))

node_application -->|"configures"| node_builder
node_application -->|"converts with"| node_gson
node_builder -->|"creates"| node_gson
node_gson -->|"delegates to"| node_type_adapter
node_gson -->|"reads from"| node_json_reader
node_gson -->|"writes to"| node_json_writer
node_gson -->|"accepts types"| node_type_token
node_type_adapter -->|"reads tokens"| node_json_reader
node_type_adapter -->|"writes tokens"| node_json_writer
node_type_adapter -->|"uses bridge"| node_streams
node_json_parser -->|"parses input"| node_json_reader
node_json_parser -->|"parses through"| node_streams
node_json_stream_parser -->|"reads stream"| node_json_reader
node_json_stream_parser -->|"parses through"| node_streams
node_runtime_adapter -->|"implements"| node_type_adapter
node_utc_adapter -->|"implements"| node_type_adapter
node_proto_adapter -.->|"adapts types"| node_type_adapter
node_legacy_proto -->|"creates adapters"| node_type_adapter
node_legacy_proto -->|"uses context"| node_gson

click node_builder "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/GsonBuilder.java"
click node_gson "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/Gson.java"
click node_type_token "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/reflect/TypeToken.java"
click node_tree_api "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/JsonElement.java"
click node_type_adapter "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/TypeAdapter.java"
click node_adapter_factory "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/TypeAdapterFactory.java"
click node_reflective_adapter "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/internal/bind/ReflectiveTypeAdapterFactory.java"
click node_collection_adapter "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/internal/bind/CollectionTypeAdapterFactory.java"
click node_built_in_adapters "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java"
click node_json_parser "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/JsonParser.java"
click node_json_stream_parser "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/JsonStreamParser.java"
click node_streams "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/internal/Streams.java"
click node_json_reader "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/stream/JsonReader.java"
click node_json_writer "https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/stream/JsonWriter.java"
click node_runtime_adapter "https://github.com/google/gson/blob/main/extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java"
click node_utc_adapter "https://github.com/google/gson/blob/main/extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java"
click node_proto_adapter "https://github.com/google/gson/blob/main/proto/src/main/java/com/google/gson/protobuf/ProtoTypeAdapter.java"
click node_legacy_proto "https://github.com/google/gson/blob/main/proto/src/main/java/com/google/gson/protobuf/LegacyProtoTypeAdapterFactory.java"

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_builder,node_gson,node_type_token,node_tree_api toneBlue
class node_type_adapter,node_adapter_factory,node_reflective_adapter,node_collection_adapter,node_built_in_adapters toneAmber
class node_json_parser,node_json_stream_parser,node_streams,node_json_reader,node_json_writer toneMint
class node_runtime_adapter,node_utc_adapter,node_proto_adapter,node_legacy_proto toneRose
class node_application toneIndigo
```

## Components

### Public API

- [GsonBuilder](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/GsonBuilder.java): `gson/src/main/java/com/google/gson/GsonBuilder.java`
- [Gson](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/Gson.java): `gson/src/main/java/com/google/gson/Gson.java`
- [TypeToken](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/reflect/TypeToken.java): `gson/src/main/java/com/google/gson/reflect/TypeToken.java`
- [JSON tree API](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/JsonElement.java): `gson/src/main/java/com/google/gson/JsonElement.java`

### Conversion Engine

- [TypeAdapter](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/TypeAdapter.java): `gson/src/main/java/com/google/gson/TypeAdapter.java`
- [Adapter factories](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/TypeAdapterFactory.java): `gson/src/main/java/com/google/gson/TypeAdapterFactory.java`
- [Reflective mapping](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/internal/bind/ReflectiveTypeAdapterFactory.java): `gson/src/main/java/com/google/gson/internal/bind/ReflectiveTypeAdapterFactory.java`
- [Collection mapping](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/internal/bind/CollectionTypeAdapterFactory.java): `gson/src/main/java/com/google/gson/internal/bind/CollectionTypeAdapterFactory.java`
- [Built-in adapters](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java): `gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java`

### JSON Processing

- [JSON parser](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/JsonParser.java): `gson/src/main/java/com/google/gson/JsonParser.java`
- [Stream parser](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/JsonStreamParser.java): `gson/src/main/java/com/google/gson/JsonStreamParser.java`
- [Tree stream bridge](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/internal/Streams.java): `gson/src/main/java/com/google/gson/internal/Streams.java`
- [JsonReader](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/stream/JsonReader.java): `gson/src/main/java/com/google/gson/stream/JsonReader.java`
- [JsonWriter](https://github.com/google/gson/blob/main/gson/src/main/java/com/google/gson/stream/JsonWriter.java): `gson/src/main/java/com/google/gson/stream/JsonWriter.java`

### Adapter Extensions

- [Runtime type adapter](https://github.com/google/gson/blob/main/extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java): `extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java`
- [UTC date adapter](https://github.com/google/gson/blob/main/extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java): `extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java`
- [Protocol Buffers adapters](https://github.com/google/gson/blob/main/proto/src/main/java/com/google/gson/protobuf/ProtoTypeAdapter.java): `proto/src/main/java/com/google/gson/protobuf/ProtoTypeAdapter.java`
- [Legacy proto adapter](https://github.com/google/gson/blob/main/proto/src/main/java/com/google/gson/protobuf/LegacyProtoTypeAdapterFactory.java): `proto/src/main/java/com/google/gson/protobuf/LegacyProtoTypeAdapterFactory.java`

### Other components

- **Java application**

## Connections

- Java application → GsonBuilder: configures (evidence: `gson/src/main/java/com/google/gson/GsonBuilder.java`)
- Java application → Gson: converts with (evidence: `README.md`)
- GsonBuilder → Gson: creates (evidence: `gson/src/main/java/com/google/gson/GsonBuilder.java`)
- Gson → TypeAdapter: delegates to (evidence: `gson/src/main/java/com/google/gson/Gson.java`)
- Gson → JsonReader: reads from (evidence: `gson/src/main/java/com/google/gson/Gson.java`)
- Gson → JsonWriter: writes to (evidence: `gson/src/main/java/com/google/gson/Gson.java`)
- Gson → TypeToken: accepts types (evidence: `gson/src/main/java/com/google/gson/Gson.java`)
- TypeAdapter → JsonReader: reads tokens (evidence: `gson/src/main/java/com/google/gson/TypeAdapter.java`)
- TypeAdapter → JsonWriter: writes tokens (evidence: `gson/src/main/java/com/google/gson/TypeAdapter.java`)
- TypeAdapter → Tree stream bridge: uses bridge (evidence: `gson/src/main/java/com/google/gson/TypeAdapter.java`)
- JSON parser → JsonReader: parses input (evidence: `gson/src/main/java/com/google/gson/JsonParser.java`)
- JSON parser → Tree stream bridge: parses through (evidence: `gson/src/main/java/com/google/gson/JsonParser.java`)
- Stream parser → JsonReader: reads stream (evidence: `gson/src/main/java/com/google/gson/JsonStreamParser.java`)
- Stream parser → Tree stream bridge: parses through (evidence: `gson/src/main/java/com/google/gson/JsonStreamParser.java`)
- Runtime type adapter → TypeAdapter: implements (evidence: `extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java`)
- UTC date adapter → TypeAdapter: implements (evidence: `extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java`)
- Protocol Buffers adapters → TypeAdapter: adapts types
- Legacy proto adapter → TypeAdapter: creates adapters (evidence: `proto/src/main/java/com/google/gson/protobuf/LegacyProtoTypeAdapterFactory.java`)
- Legacy proto adapter → Gson: uses context (evidence: `proto/src/main/java/com/google/gson/protobuf/LegacyProtoTypeAdapterFactory.java`)
