# protocolbuffers/protobuf architecture

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

- Interactive diagram: https://gitdiagram.com/protocolbuffers/protobuf
- Repository: https://github.com/protocolbuffers/protobuf

## Overview

Protocol Buffers provides a schema-driven compiler and language-specific runtimes for serializing structured data. The principal workflow is: users define .proto schemas, protoc parses them and dispatches language generators, generated message types run on a language runtime, and applications serialize or parse wire-format data. Reflection and descriptor databases support schema introspection and lookup. The README documents additional language runtimes, but this tree sample does not expose all implementations, so those are represented only where repository paths support them; several internal runtime links are omitted rather than inferred.

Main entry points: [`csharp/src/Google.Protobuf.Conformance/Program.cs`](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf.Conformance/Program.cs) (C# conformance runner), [`src/google/protobuf/compiler/main.cc`](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/compiler/main.cc) (protoc CLI), [`java/core/src/main/java/com/google/protobuf/Message.java`](https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/Message.java) (Java messages), [`csharp/src/Google.Protobuf/IMessage.cs`](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/IMessage.cs) (C# message API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Compiler and generation"]
  node_proto_files["Proto schemas"]
  node_protoc["protoc CLI<br/>[main.cc]"]
  node_upb_gen["upb mini-table generator<br/>[main.cc]"]
  node_generated["Generated message types"]
end

subgraph group_schema["Schema reflection"]
  node_cpp_descriptor_db[("C++ descriptor database")]
  node_python_descriptor_db[("Python descriptor database")]
  node_java_reflection["Java descriptors<br/>[Descriptors.java]"]
  node_csharp_reflection["C&#35; reflection"]
  node_csharp_field_descriptor["C&#35; field metadata<br/>[FieldDescriptor.cs]"]
  node_csharp_type_registry["C&#35; type registry<br/>[TypeRegistry.cs]"]
end

subgraph group_runtime["Language runtimes"]
  node_java_messages["Java messages<br/>[Message.java]"]
  node_java_lite["Java lite messages<br/>[MessageLite.java]"]
  node_java_wire["Java coded input"]
  node_java_bytes["Java byte strings<br/>[ByteString.java]"]
  node_csharp_messages["C&#35; message API<br/>[IMessage.cs]"]
  node_csharp_input["C&#35; coded input"]
  node_csharp_bytes["C&#35; byte strings<br/>[ByteString.cs]"]
  node_csharp_json["C&#35; JSON conversion<br/>[JsonParser.cs]"]
  node_csharp_formatter["C&#35; JSON formatter<br/>[JsonFormatter.cs]"]
  node_upb_runtime["upb runtime<br/>[arena.c]"]
  node_rust_upb["Rust upb bindings<br/>[mod.rs]"]
end

subgraph group_interop["Services and conformance"]
  node_java_service["Java service API<br/>[Service.java]"]
  node_ruby_service["JRuby service descriptors"]
  node_csharp_conformance["C&#35; conformance runner<br/>[Program.cs]"]
  node_conformance_protocol["Conformance protocol<br/>[conformance.proto]"]
end

node_user(("Application developer"))
node_schema_author(("Schema author"))

node_schema_author -->|"defines schema"| node_proto_files
node_user -->|"invokes compiler"| node_protoc
node_proto_files -->|"compiles schema"| node_protoc
node_protoc -->|"generates code"| node_generated
node_protoc -.->|"supports plugins"| node_upb_gen
node_generated -.->|"uses runtime"| node_java_messages
node_generated -.->|"uses runtime"| node_csharp_messages
node_generated -.->|"uses runtime"| node_rust_upb
node_user -->|"uses runtime"| node_java_messages
node_user -->|"uses runtime"| node_csharp_messages
node_java_messages -->|"exposes descriptors"| node_java_reflection
node_java_messages -.->|"parses wire data"| node_java_wire
node_csharp_messages -->|"merges input"| node_csharp_input
node_csharp_messages -->|"exposes descriptor"| node_csharp_reflection
node_csharp_reflection -.->|"describes fields"| node_csharp_field_descriptor
node_csharp_type_registry -->|"resolves message types"| node_csharp_conformance
node_csharp_conformance -->|"reads requests"| node_conformance_protocol
node_csharp_conformance -->|"parses JSON"| node_csharp_json
node_csharp_conformance -->|"formats JSON"| node_csharp_formatter
node_python_descriptor_db -->|"uses descriptor types"| node_cpp_descriptor_db
node_java_service -->|"uses service descriptors"| node_java_reflection
node_ruby_service -.->|"wraps service metadata"| node_java_reflection

click node_protoc "https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/compiler/main.cc"
click node_upb_gen "https://github.com/protocolbuffers/protobuf/blob/main/upb_generator/minitable/main.cc"
click node_cpp_descriptor_db "https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor_database.cc"
click node_python_descriptor_db "https://github.com/protocolbuffers/protobuf/blob/main/python/google/protobuf/pyext/descriptor_database.cc"
click node_java_reflection "https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/Descriptors.java"
click node_csharp_reflection "https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/Reflection/MessageDescriptor.cs"
click node_csharp_field_descriptor "https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs"
click node_csharp_type_registry "https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/Reflection/TypeRegistry.cs"
click node_java_messages "https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/Message.java"
click node_java_lite "https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/MessageLite.java"
click node_java_wire "https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/CodedInputStream.java"
click node_java_bytes "https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/ByteString.java"
click node_csharp_messages "https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/IMessage.cs"
click node_csharp_input "https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/CodedInputStream.cs"
click node_csharp_bytes "https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/ByteString.cs"
click node_csharp_json "https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/JsonParser.cs"
click node_csharp_formatter "https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/JsonFormatter.cs"
click node_upb_runtime "https://github.com/protocolbuffers/protobuf/blob/main/upb/mem/arena.c"
click node_rust_upb "https://github.com/protocolbuffers/protobuf/blob/main/rust/upb_kernel/mod.rs"
click node_java_service "https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/Service.java"
click node_ruby_service "https://github.com/protocolbuffers/protobuf/blob/main/ruby/src/main/java/com/google/protobuf/jruby/RubyServiceDescriptor.java"
click node_csharp_conformance "https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf.Conformance/Program.cs"
click node_conformance_protocol "https://github.com/protocolbuffers/protobuf/blob/main/conformance/conformance.proto"

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_proto_files,node_protoc,node_upb_gen,node_generated toneBlue
class node_cpp_descriptor_db,node_python_descriptor_db,node_java_reflection,node_csharp_reflection,node_csharp_field_descriptor,node_csharp_type_registry toneAmber
class node_java_messages,node_java_lite,node_java_wire,node_java_bytes,node_csharp_messages,node_csharp_input,node_csharp_bytes,node_csharp_json,node_csharp_formatter,node_upb_runtime,node_rust_upb toneMint
class node_java_service,node_ruby_service,node_csharp_conformance,node_conformance_protocol toneRose
class node_user,node_schema_author toneIndigo
```

## Components

### Compiler and generation

- **Proto schemas**
- [protoc CLI](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/compiler/main.cc): `src/google/protobuf/compiler/main.cc`
- [upb mini-table generator](https://github.com/protocolbuffers/protobuf/blob/main/upb_generator/minitable/main.cc): `upb_generator/minitable/main.cc`
- **Generated message types**

### Schema reflection

- [C++ descriptor database](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor_database.cc): `src/google/protobuf/descriptor_database.cc`
- [Python descriptor database](https://github.com/protocolbuffers/protobuf/blob/main/python/google/protobuf/pyext/descriptor_database.cc): `python/google/protobuf/pyext/descriptor_database.cc`
- [Java descriptors](https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/Descriptors.java): `java/core/src/main/java/com/google/protobuf/Descriptors.java`
- [C# reflection](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/Reflection/MessageDescriptor.cs): `csharp/src/Google.Protobuf/Reflection/MessageDescriptor.cs`
- [C# field metadata](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs): `csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs`
- [C# type registry](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/Reflection/TypeRegistry.cs): `csharp/src/Google.Protobuf/Reflection/TypeRegistry.cs`

### Language runtimes

- [Java messages](https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/Message.java): `java/core/src/main/java/com/google/protobuf/Message.java`
- [Java lite messages](https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/MessageLite.java): `java/core/src/main/java/com/google/protobuf/MessageLite.java`
- [Java coded input](https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/CodedInputStream.java): `java/core/src/main/java/com/google/protobuf/CodedInputStream.java`
- [Java byte strings](https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/ByteString.java): `java/core/src/main/java/com/google/protobuf/ByteString.java`
- [C# message API](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/IMessage.cs): `csharp/src/Google.Protobuf/IMessage.cs`
- [C# coded input](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/CodedInputStream.cs): `csharp/src/Google.Protobuf/CodedInputStream.cs`
- [C# byte strings](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/ByteString.cs): `csharp/src/Google.Protobuf/ByteString.cs`
- [C# JSON conversion](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/JsonParser.cs): `csharp/src/Google.Protobuf/JsonParser.cs`
- [C# JSON formatter](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf/JsonFormatter.cs): `csharp/src/Google.Protobuf/JsonFormatter.cs`
- [upb runtime](https://github.com/protocolbuffers/protobuf/blob/main/upb/mem/arena.c): `upb/mem/arena.c`
- [Rust upb bindings](https://github.com/protocolbuffers/protobuf/blob/main/rust/upb_kernel/mod.rs): `rust/upb_kernel/mod.rs`

### Services and conformance

- [Java service API](https://github.com/protocolbuffers/protobuf/blob/main/java/core/src/main/java/com/google/protobuf/Service.java): `java/core/src/main/java/com/google/protobuf/Service.java`
- [JRuby service descriptors](https://github.com/protocolbuffers/protobuf/blob/main/ruby/src/main/java/com/google/protobuf/jruby/RubyServiceDescriptor.java): `ruby/src/main/java/com/google/protobuf/jruby/RubyServiceDescriptor.java`
- [C# conformance runner](https://github.com/protocolbuffers/protobuf/blob/main/csharp/src/Google.Protobuf.Conformance/Program.cs): `csharp/src/Google.Protobuf.Conformance/Program.cs`
- [Conformance protocol](https://github.com/protocolbuffers/protobuf/blob/main/conformance/conformance.proto): `conformance/conformance.proto`

### Other components

- **Application developer**
- **Schema author**

## Connections

- Schema author → Proto schemas: defines schema
- Application developer → protoc CLI: invokes compiler
- Proto schemas → protoc CLI: compiles schema
- protoc CLI → Generated message types: generates code (evidence: `src/google/protobuf/compiler/main.cc`)
- protoc CLI → upb mini-table generator: supports plugins
- Generated message types → Java messages: uses runtime
- Generated message types → C# message API: uses runtime
- Generated message types → Rust upb bindings: uses runtime
- Application developer → Java messages: uses runtime
- Application developer → C# message API: uses runtime
- Java messages → Java descriptors: exposes descriptors (evidence: `java/core/src/main/java/com/google/protobuf/Message.java`)
- Java messages → Java coded input: parses wire data (evidence: `java/core/src/main/java/com/google/protobuf/Message.java`)
- C# message API → C# coded input: merges input (evidence: `csharp/src/Google.Protobuf/IMessage.cs`)
- C# message API → C# reflection: exposes descriptor (evidence: `csharp/src/Google.Protobuf/IMessage.cs`)
- C# reflection → C# field metadata: describes fields
- C# type registry → C# conformance runner: resolves message types (evidence: `csharp/src/Google.Protobuf.Conformance/Program.cs`)
- C# conformance runner → Conformance protocol: reads requests (evidence: `csharp/src/Google.Protobuf.Conformance/Program.cs`)
- C# conformance runner → C# JSON conversion: parses JSON (evidence: `csharp/src/Google.Protobuf.Conformance/Program.cs`)
- C# conformance runner → C# JSON formatter: formats JSON (evidence: `csharp/src/Google.Protobuf.Conformance/Program.cs`)
- Python descriptor database → C++ descriptor database: uses descriptor types (evidence: `python/google/protobuf/pyext/descriptor_database.cc`)
- Java service API → Java descriptors: uses service descriptors (evidence: `java/core/src/main/java/com/google/protobuf/Service.java`)
- JRuby service descriptors → Java descriptors: wraps service metadata (evidence: `ruby/src/main/java/com/google/protobuf/jruby/RubyServiceDescriptor.java`)
