# victoriametrics/easyproto architecture

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

- Interactive diagram: https://gitdiagram.com/victoriametrics/easyproto
- Repository: https://github.com/victoriametrics/easyproto

## Overview

##### Project type and purpose
- Project type: Go library for zero-alloc protobuf (proto3) marshaling/unmarshaling.
- Purpose: Provide building blocks (in Go code) to serialize and deserialize protobuf messages without invoking `protoc` or `go generate`.

##### File structure
Top-level files:
- writer.go – implements marshaling logic (MessageMarshaler) and MarshalerPool
- reader.go – implements unmarshaling logic (FieldContext)
- doc.go – package documentation
- easyproto_example_test.go, easyproto_test.go, easyproto_timing_test.go – examples and tests
- go.mod – module definition
- LICENSE, README.md – metadata

Architectural pattern: A single library component subdivided into two main submodules (writer + reader), with a small pooling utility.

##### README
- No external services—pure in-process library.
- Public API surfaces:
– `easyproto.Marshaler`, `MarshalerPool`, `MessageMarshaler` (in writer.go)
– `easyproto.FieldContext` (in reader.go)
- Usage flows described:
– Client struct implements `MarshalProtobuf(dst []byte) []byte` by acquiring a buffer from `MarshalerPool`, appending fields, then releasing it.
– Client struct implements `UnmarshalProtobuf(src []byte)` by looping with `FieldContext.NextField` and switching on `FieldNum`.

##### Main components and interactions
a. Components:
– Client code (user’s Go structs and methods)
– easyproto library
- MarshalerPool (pool of Marshaler instances)
- MessageMarshaler (writer submodule)
- FieldContext (reader submodule)
– Byte buffer (`[]byte`)
b. Relationships & data flows:
– Client calls `MarshalProtobuf(dst)` → obtains `Marshaler` from `MarshalerPool` → uses `MessageMarshaler` to `Append*` fields → calls `Marshal()` → returns extended `[]byte` → returns pool.
– Client calls `UnmarshalProtobuf(src)` → creates `FieldContext` → loops `NextField(src)` → extracts values via `FieldContext.String()`, `Double()`, `Int64()`, or `MessageData()` → populates client struct fields.
c. Architectural patterns & principles:
– Pooling for zero-alloc reuse (resource pool pattern)
– Separation of concerns: writing vs reading submodules
– Minimal dependencies: no protoc, pure Go
d. Key technologies:
– Go language (go.mod)
– Protobuf (proto3 encoding, no codegen)
– Standard library (slices, io)

– Component names and responsibilities

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Code" 
        direction TB
        ClientStruct["Client Struct\nMarshalProtobuf()/UnmarshalProtobuf()"]:::client
        Example1["easyproto_example_test.go"]:::client
        Example2["easyproto_test.go"]:::client
        Example3["easyproto_timing_test.go"]:::client
    end

    subgraph "easyproto Public API"
        direction TB
        MarshalerPool["MarshalerPool\n(Get/Put)"]:::api
        API_Docs["Public API Docs (doc.go)"]:::api
    end

    subgraph "Internal Modules"
        direction TB
        MessageMarshaler["MessageMarshaler\nAppend*/Marshal"]:::internal
        FieldContext["FieldContext\nNextField/String/Double/Int64/MessageData"]:::internal
        Buffer["[]byte buffer"]:::internal
    end

    ClientStruct -->|"MarshalProtobuf"| MarshalerPool
    MarshalerPool -->|"Get Marshaler"| MessageMarshaler
    MessageMarshaler -->|"Marshal() -> bytes"| Buffer
    Buffer -->|"Return bytes"| ClientStruct

    ClientStruct -->|"UnmarshalProtobuf"| FieldContext
    FieldContext -->|"Extract values"| ClientStruct

    Example1 --> ClientStruct
    Example2 --> ClientStruct
    Example3 --> ClientStruct

    click MarshalerPool "https://github.com/victoriametrics/easyproto/blob/master/writer.go"
    click MessageMarshaler "https://github.com/victoriametrics/easyproto/blob/master/writer.go"
    click FieldContext "https://github.com/victoriametrics/easyproto/blob/master/reader.go"
    click API_Docs "https://github.com/victoriametrics/easyproto/blob/master/doc.go"
    click Example1 "https://github.com/victoriametrics/easyproto/blob/master/easyproto_example_test.go"
    click Example2 "https://github.com/victoriametrics/easyproto/blob/master/easyproto_test.go"
    click Example3 "https://github.com/victoriametrics/easyproto/blob/master/easyproto_timing_test.go"

    classDef client fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef api fill:#90EE90,stroke:#000,stroke-width:1px
    classDef internal fill:#FFFFE0,stroke:#000,stroke-width:1px
```
