# hebirobotics/quickbuffers architecture

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

- Interactive diagram: https://gitdiagram.com/hebirobotics/quickbuffers
- Repository: https://github.com/hebirobotics/quickbuffers

## Overview

##### Main Components Overview
The system consists of several key modules that should be represented as distinct components:

a) Core Components:
- quickbuf-runtime: The main runtime library
- protoc-gen-quickbuf: The code generator plugin
- quickbuf-compat: Compatibility layer for JSON libraries
- conformance: Conformance testing module
- benchmarks: Performance testing module

##### Architecture Layers

**┌─────────────────────────────────────────────────────────┐**
- Client Application                     │
- ┬─────────────────────────────┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- QuickBuf Runtime                     │
- ┬──────────────┬────────────┬──────────────┤
- ProtoMessage│  JSON Support│   Memory   │ Compatibility │
- Core     │             │  Management │    Layer      │
- ┴──────────────┴────────────┴──────────────┘
- ↑
**┌─────────────────────────────────────────────────────────┐**
- Code Generation Layer                    │
- ┬──────────────┬────────────┬──────────────┤
- Proto File │   Generator  │  Template  │   Plugin     │
- Parser    │    Core      │  Engine    │   System     │
- ┴──────────────┴────────────┴──────────────┘

##### Data Flow Representation

a) Message Generation Flow:
**.proto files → protoc → protoc-gen-quickbuf → Generated Java Classes**

b) Runtime Data Flow:
**Raw Data → ProtoSource → ProtoMessage → ProtoSink → Serialized Output**

##### Component Details

Core Runtime (quickbuf-runtime):
- Memory management components (ArraySource, DirectSource)
- JSON processing (JsonSink, JsonSource)
- Message handling (ProtoMessage, RepeatedField)

Code Generator (protoc-gen-quickbuf):
- Plugin interface with protoc
- Code generation components
- Template processing system

##### Integration Points

External Systems:
- Protocol Buffers compiler (protoc)
- JSON libraries (through quickbuf-compat)
- Client applications

##### Key Features to Highlight

Performance Optimizations:
- Zero-allocation design
- Direct memory access
- Reusable objects

Format Support:
- Protocol Buffers encoding/decoding
- JSON serialization/deserialization
- Direct memory operations

##### Additional Elements

Annotations for:
- Memory management strategies
- Performance characteristics
- Configuration options
- Compatibility interfaces

- The zero-allocation design
- The separation between generation and runtime
- The flexible memory management system
- The various serialization formats supported

Remember to:
- Keep components visually distinct
- Use consistent styling
- Brief descriptions for key components

This design captures the essence of QuickBuffers as a high-performance, allocation-free Protocol Buffers implementation while showing the relationships between its various components and subsystems.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Application Layer
    subgraph CL[Client Layer]
        CA[Client Application]
    end

    %% Runtime Layer
    subgraph RL[Runtime Layer]
        subgraph Core[ProtoMessage Core]
            PM[ProtoMessage]
            PS[ProtoSink]
            PSrc[ProtoSource]
        end

        subgraph JSON[JSON Support]
            JS[JsonSink]
            JSrc[JsonSource]
            JE[JsonEncoding]
            JD[JsonDecoding]
        end

        subgraph MM[Memory Management]
            AS[ArraySink]
            ASrc[ArraySource]
            UA[UnsafeAccess]
        end

        subgraph CL[Compatibility Layer]
            GS[GsonSink]
            GSrc[GsonSource]
            JKS[JacksonSink]
            JKSrc[JacksonSource]
        end
    end

    %% Code Generation Layer
    subgraph GL[Code Generation Layer]
        subgraph GC[Generator Components]
            QP[QuickbufPlugin]
            MG[MessageGenerator]
            FG[FieldGenerator]
            EG[EnumGenerator]
        end

        subgraph Testing[Testing Components]
            PB[Performance Benchmarks]
            CT[Conformance Tests]
        end
    end

    %% Relationships
    CA --> PM
    PM --> PS
    PM --> PSrc
    PS --> JS
    PSrc --> JSrc
    JS --> JE
    JSrc --> JD
    PS --> AS
    PSrc --> ASrc
    AS --> UA
    ASrc --> UA
    JS --> GS
    JSrc --> GSrc
    JS --> JKS
    JSrc --> JKSrc
    QP --> MG
    MG --> FG
    MG --> EG
    PB --> PM
    CT --> PM

    %% Click Events
    click PM "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/ProtoMessage.java"
    click PS "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/ProtoSink.java"
    click PSrc "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/ProtoSource.java"
    click JS "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/JsonSink.java"
    click JSrc "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/JsonSource.java"
    click JE "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/JsonEncoding.java"
    click JD "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/JsonDecoding.java"
    click AS "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/ArraySink.java"
    click ASrc "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/ArraySource.java"
    click UA "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-runtime/src/main/java/us/hebi/quickbuf/UnsafeAccess.java"
    click GS "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-compat/src/main/java/us/hebi/quickbuf/compat/GsonSink.java"
    click GSrc "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-compat/src/main/java/us/hebi/quickbuf/compat/GsonSource.java"
    click JKS "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-compat/src/main/java/us/hebi/quickbuf/compat/JacksonSink.java"
    click JKSrc "https://github.com/HebiRobotics/QuickBuffers/blob/main/quickbuf-compat/src/main/java/us/hebi/quickbuf/compat/JacksonSource.java"
    click QP "https://github.com/HebiRobotics/QuickBuffers/blob/main/protoc-gen-quickbuf/src/main/java/us/hebi/quickbuf/generator/QuickbufPlugin.java"
    click MG "https://github.com/HebiRobotics/QuickBuffers/blob/main/protoc-gen-quickbuf/src/main/java/us/hebi/quickbuf/generator/MessageGenerator.java"
    click FG "https://github.com/HebiRobotics/QuickBuffers/blob/main/protoc-gen-quickbuf/src/main/java/us/hebi/quickbuf/generator/FieldGenerator.java"
    click EG "https://github.com/HebiRobotics/QuickBuffers/blob/main/protoc-gen-quickbuf/src/main/java/us/hebi/quickbuf/generator/EnumGenerator.java"
    click PB "https://github.com/HebiRobotics/QuickBuffers/tree/main/benchmarks/src/main/java/us/hebi/quickbuf/benchmarks/encoding"
    click CT "https://github.com/HebiRobotics/QuickBuffers/blob/main/conformance/src/main/java/us/hebi/quickbuf/conformance/ConformanceQuickbuf.java"

    %% Styling
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px
    classDef core fill:#d4e6f1,stroke:#2874a6
    classDef json fill:#d5f5e3,stroke:#196f3d
    classDef memory fill:#fdebd0,stroke:#d35400
    classDef compat fill:#ebdef0,stroke:#8e44ad
    classDef generator fill:#f2d7d5,stroke:#c0392b
    classDef testing fill:#eaecee,stroke:#2c3e50

    class PM,PS,PSrc core
    class JS,JSrc,JE,JD json
    class AS,ASrc,UA memory
    class GS,GSrc,JKS,JKSrc compat
    class QP,MG,FG,EG generator
    class PB,CT testing
```
