# apache/avro architecture

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

- Interactive diagram: https://gitdiagram.com/apache/avro
- Repository: https://github.com/apache/avro

## Overview

Apache Avro is a cross-language data serialization system. Its principal workflow is to define or parse a schema, encode data using that schema, then decode it—optionally resolving differences between the writer’s and reader’s schemas. The repository also includes container-file, RPC, code-generation, and Hadoop tether capabilities. The source index supports several Python, C, C++, C#, Java gRPC, and tool-dispatch relationships; other language modules are represented as capabilities, without inferred call paths where source was not sampled.

Main entry points: [`lang/py/avro/schema.py`](https://github.com/apache/avro/blob/main/lang/py/avro/schema.py) (Python schemas), [`lang/py/avro/ipc.py`](https://github.com/apache/avro/blob/main/lang/py/avro/ipc.py) (Python IPC), [`lang/csharp/src/apache/ipc.test/HttpClientServerTest.cs`](https://github.com/apache/avro/blob/main/lang/csharp/src/apache/ipc.test/HttpClientServerTest.cs) (C# HTTP RPC example), [`lang/py/avro/io.py`](https://github.com/apache/avro/blob/main/lang/py/avro/io.py) (Python datum IO)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_schema["Schemas and data"]
  node_py_schema["Python schemas<br/>[schema.py]"]
  node_java_schema["Java schemas<br/>[Schema.java]"]
  node_js_schema["JavaScript schemas<br/>[schemas.js]"]
  node_c_schema["C schemas<br/>[schema.h]"]
  node_c_values["C datum values<br/>[value.h]"]
  node_cs_schema["C&#35; schemas<br/>[Schema.cs]"]
  node_cs_records["C&#35; generic records<br/>[GenericRecord.cs]"]
  node_php_schema["PHP schemas<br/>[AvroSchema.php]"]
end

subgraph group_encoding["Encoding and resolution"]
  node_py_io["Python datum IO<br/>[io.py]"]
  node_php_reader["PHP datum reader"]
  node_cpp_resolver["C++ schema resolution"]
  node_c_resolver["C resolved reader<br/>[resolved-reader.c]"]
  node_ruby_io["Ruby datum IO<br/>[io.rb]"]
  node_csharp_parsing["C&#35; parsing symbols<br/>[Symbol.cs]"]
end

subgraph group_files["Container files"]
  node_java_files["Java data files"]
  node_php_files["PHP data files"]
end

subgraph group_rpc["RPC and integration"]
  node_py_ipc["Python IPC<br/>[ipc.py]"]
  node_java_grpc["Java gRPC client"]
  node_cs_ipc_test["C&#35; HTTP RPC example"]
  node_java_protocol["Java protocols<br/>[Protocol.java]"]
  node_mapred_tether["MapReduce tether output"]
end

subgraph group_tools["Tools and generation"]
  node_java_tools["Java CLI tools<br/>[Main.java]"]
  node_cpp_codegen["C++ code generator<br/>[avrogencpp.cc]"]
end

node_user(("Avro user"))

node_user -->|"defines schema"| node_py_schema
node_py_schema -->|"supplies schema"| node_py_io
node_py_ipc -->|"uses datum IO"| node_py_io
node_py_ipc -->|"uses schemas"| node_py_schema
node_php_reader -->|"matches schemas"| node_php_schema
node_java_grpc -->|"gets protocol"| node_java_protocol
node_java_tools -->|"dispatches commands"| node_user
node_cpp_codegen -->|"generates C++ types"| node_user
node_cs_ipc_test -->|"sends records"| node_cs_records
node_cs_ipc_test -.->|"uses protocol"| node_java_protocol

click node_py_schema "https://github.com/apache/avro/blob/main/lang/py/avro/schema.py"
click node_java_schema "https://github.com/apache/avro/blob/main/lang/java/avro/src/main/java/org/apache/avro/Schema.java"
click node_js_schema "https://github.com/apache/avro/blob/main/lang/js/lib/schemas.js"
click node_c_schema "https://github.com/apache/avro/blob/main/lang/c/src/avro/schema.h"
click node_c_values "https://github.com/apache/avro/blob/main/lang/c/src/avro/value.h"
click node_cs_schema "https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/Schema/Schema.cs"
click node_cs_records "https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/Generic/GenericRecord.cs"
click node_php_schema "https://github.com/apache/avro/blob/main/lang/php/lib/Schema/AvroSchema.php"
click node_py_io "https://github.com/apache/avro/blob/main/lang/py/avro/io.py"
click node_php_reader "https://github.com/apache/avro/blob/main/lang/php/lib/Datum/AvroIODatumReader.php"
click node_cpp_resolver "https://github.com/apache/avro/blob/main/lang/c%2B%2B/impl/parsing/ResolvingDecoder.cc"
click node_c_resolver "https://github.com/apache/avro/blob/main/lang/c/src/resolved-reader.c"
click node_py_ipc "https://github.com/apache/avro/blob/main/lang/py/avro/ipc.py"
click node_java_grpc "https://github.com/apache/avro/blob/main/lang/java/grpc/src/main/java/org/apache/avro/grpc/AvroGrpcClient.java"
click node_cs_ipc_test "https://github.com/apache/avro/blob/main/lang/csharp/src/apache/ipc.test/HttpClientServerTest.cs"
click node_java_protocol "https://github.com/apache/avro/blob/main/lang/java/avro/src/main/java/org/apache/avro/Protocol.java"
click node_java_files "https://github.com/apache/avro/blob/main/lang/java/avro/src/main/java/org/apache/avro/file/DataFileWriter.java"
click node_php_files "https://github.com/apache/avro/blob/main/lang/php/lib/DataFile/AvroDataIOReader.php"
click node_java_tools "https://github.com/apache/avro/blob/main/lang/java/tools/src/main/java/org/apache/avro/tool/Main.java"
click node_cpp_codegen "https://github.com/apache/avro/blob/main/lang/c%2B%2B/impl/avrogencpp.cc"
click node_mapred_tether "https://github.com/apache/avro/blob/main/lang/java/mapred/src/main/java/org/apache/avro/mapred/tether/TetherOutputService.java"
click node_ruby_io "https://github.com/apache/avro/blob/main/lang/ruby/lib/avro/io.rb"
click node_csharp_parsing "https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/IO/Parsing/Symbol.cs"

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_py_schema,node_java_schema,node_js_schema,node_c_schema,node_c_values,node_cs_schema,node_cs_records,node_php_schema,node_user toneBlue
class node_py_io,node_php_reader,node_cpp_resolver,node_c_resolver,node_ruby_io,node_csharp_parsing toneAmber
class node_java_files,node_php_files toneMint
class node_py_ipc,node_java_grpc,node_cs_ipc_test,node_java_protocol,node_mapred_tether toneRose
class node_java_tools,node_cpp_codegen toneIndigo
```

## Components

### Schemas and data

- [Python schemas](https://github.com/apache/avro/blob/main/lang/py/avro/schema.py): `lang/py/avro/schema.py`
- [Java schemas](https://github.com/apache/avro/blob/main/lang/java/avro/src/main/java/org/apache/avro/Schema.java): `lang/java/avro/src/main/java/org/apache/avro/Schema.java`
- [JavaScript schemas](https://github.com/apache/avro/blob/main/lang/js/lib/schemas.js): `lang/js/lib/schemas.js`
- [C schemas](https://github.com/apache/avro/blob/main/lang/c/src/avro/schema.h): `lang/c/src/avro/schema.h`
- [C datum values](https://github.com/apache/avro/blob/main/lang/c/src/avro/value.h): `lang/c/src/avro/value.h`
- [C# schemas](https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/Schema/Schema.cs): `lang/csharp/src/apache/main/Schema/Schema.cs`
- [C# generic records](https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/Generic/GenericRecord.cs): `lang/csharp/src/apache/main/Generic/GenericRecord.cs`
- [PHP schemas](https://github.com/apache/avro/blob/main/lang/php/lib/Schema/AvroSchema.php): `lang/php/lib/Schema/AvroSchema.php`

### Encoding and resolution

- [Python datum IO](https://github.com/apache/avro/blob/main/lang/py/avro/io.py): `lang/py/avro/io.py`
- [PHP datum reader](https://github.com/apache/avro/blob/main/lang/php/lib/Datum/AvroIODatumReader.php): `lang/php/lib/Datum/AvroIODatumReader.php`
- [C++ schema resolution](https://github.com/apache/avro/blob/main/lang/c%2B%2B/impl/parsing/ResolvingDecoder.cc): `lang/c++/impl/parsing/ResolvingDecoder.cc`
- [C resolved reader](https://github.com/apache/avro/blob/main/lang/c/src/resolved-reader.c): `lang/c/src/resolved-reader.c`
- [Ruby datum IO](https://github.com/apache/avro/blob/main/lang/ruby/lib/avro/io.rb): `lang/ruby/lib/avro/io.rb`
- [C# parsing symbols](https://github.com/apache/avro/blob/main/lang/csharp/src/apache/main/IO/Parsing/Symbol.cs): `lang/csharp/src/apache/main/IO/Parsing/Symbol.cs`

### Container files

- [Java data files](https://github.com/apache/avro/blob/main/lang/java/avro/src/main/java/org/apache/avro/file/DataFileWriter.java): `lang/java/avro/src/main/java/org/apache/avro/file/DataFileWriter.java`
- [PHP data files](https://github.com/apache/avro/blob/main/lang/php/lib/DataFile/AvroDataIOReader.php): `lang/php/lib/DataFile/AvroDataIOReader.php`

### RPC and integration

- [Python IPC](https://github.com/apache/avro/blob/main/lang/py/avro/ipc.py): `lang/py/avro/ipc.py`
- [Java gRPC client](https://github.com/apache/avro/blob/main/lang/java/grpc/src/main/java/org/apache/avro/grpc/AvroGrpcClient.java): `lang/java/grpc/src/main/java/org/apache/avro/grpc/AvroGrpcClient.java`
- [C# HTTP RPC example](https://github.com/apache/avro/blob/main/lang/csharp/src/apache/ipc.test/HttpClientServerTest.cs): `lang/csharp/src/apache/ipc.test/HttpClientServerTest.cs`
- [Java protocols](https://github.com/apache/avro/blob/main/lang/java/avro/src/main/java/org/apache/avro/Protocol.java): `lang/java/avro/src/main/java/org/apache/avro/Protocol.java`
- [MapReduce tether output](https://github.com/apache/avro/blob/main/lang/java/mapred/src/main/java/org/apache/avro/mapred/tether/TetherOutputService.java): `lang/java/mapred/src/main/java/org/apache/avro/mapred/tether/TetherOutputService.java`

### Tools and generation

- [Java CLI tools](https://github.com/apache/avro/blob/main/lang/java/tools/src/main/java/org/apache/avro/tool/Main.java): `lang/java/tools/src/main/java/org/apache/avro/tool/Main.java`
- [C++ code generator](https://github.com/apache/avro/blob/main/lang/c%2B%2B/impl/avrogencpp.cc): `lang/c++/impl/avrogencpp.cc`

### Other components

- **Avro user**

## Connections

- Avro user → Python schemas: defines schema (evidence: `README.md`)
- Python schemas → Python datum IO: supplies schema (evidence: `lang/py/avro/io.py`)
- Python IPC → Python datum IO: uses datum IO (evidence: `lang/py/avro/ipc.py`)
- Python IPC → Python schemas: uses schemas (evidence: `lang/py/avro/ipc.py`)
- PHP datum reader → PHP schemas: matches schemas (evidence: `lang/php/lib/Datum/AvroIODatumReader.php`)
- Java gRPC client → Java protocols: gets protocol (evidence: `lang/java/grpc/src/main/java/org/apache/avro/grpc/AvroGrpcClient.java`)
- Java CLI tools → Avro user: dispatches commands (evidence: `lang/java/tools/src/main/java/org/apache/avro/tool/Main.java`)
- C++ code generator → Avro user: generates C++ types (evidence: `lang/c++/impl/avrogencpp.cc`)
- C# HTTP RPC example → C# generic records: sends records (evidence: `lang/csharp/src/apache/ipc.test/HttpClientServerTest.cs`)
- C# HTTP RPC example → Java protocols: uses protocol