# aeron-io/agrona architecture

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

- Interactive diagram: https://gitdiagram.com/aeron-io/agrona
- Repository: https://github.com/aeron-io/agrona

## Overview

##### Project Type and Purpose
- Agrona is an open-source, multi-module Java library aimed at providing high-performance data structures, buffers, and utility methods for low-latency applications.
- It is not a client/server or full-stack application; rather it is a collection of reusable modules (core library, Java agent, benchmarks, tests) that integrate with other systems (e.g., Aeron, SBE).

##### High-Level File/Module Structure
- Top-level modules:
- agrona           – The core library containing packages such as `collections`, `concurrent`, `io`, `sbe`, etc.
- agrona-agent     – A Java instrumentation agent for buffer alignment and interception (`BufferAlignmentAgent`).
- agrona-benchmarks– Benchmark applications exercising key components (e.g., ring buffers, parsing).
- agrona-concurrency-tests – A test harness for concurrency primitives.
- buildSrc         – Custom Gradle plugin code (e.g., `UnsafeApiBytecodeGenerator`, `SonatypeCentralPortalUploadRepositoryTask`).
- Build & config:
- Gradle wrapper (`gradlew`, `gradle/wrapper`) + `build.gradle`, `settings.gradle`, `gradle/libs.versions.toml`.
- CI workflows under `.github/workflows` (CI, CodeQL, release).
- Checkstyle config in `config/checkstyle`.

##### Key Architectural Components
- Core Library (agrona):
- Package subdivision by functionality (buffers, collections, concurrency, IO, NIO, sbe, checksum, generation).
- Utilities for off-heap buffers, lock-free queues, timers, error logging.
- Instrumentation Agent (agrona-agent):
- Java `premain` agent that applies bytecode interception to ensure buffer alignment.
- Benchmarks:
- Standalone Java apps measuring performance of select features.
- Concurrency Tests:
- JUnit test suite for verifying correctness of lock-free structures under contention.
- Build Extension (buildSrc):
- Custom generators for Unsafe APIs and release tasks for Maven Central.
- External Integrations:
- GitHub Actions for CI, CodeQL scanning, and artifact publishing.
- Maven Central for dependency distribution.

##### Relationships & Data Flows
- Build Flow:
- Gradle → invokes buildSrc plugins → compiles core & sub-modules → runs tests & benchmarks → packages artifacts → CI pipelines → publishes to Maven.
- Module Dependencies:
- `agrona-agent` depends on `agrona` core.
- `agrona-benchmarks` and `agrona-concurrency-tests` depend on `agrona` core.
- Runtime/Consumer Flow:
- End applications import `agrona` from Maven.
- Optionally attach `agrona-agent` at JVM startup for buffer alignment behavior.

- Blue for modules
- Orange for build/process components
- Gray for external systems

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Agrona Modules
    subgraph "Agrona Modules"
        Core["agrona\n(core library)"] 
        Agent["agrona-agent\n(instrumentation agent)"]
        Benchmarks["agrona-benchmarks\n(benchmarks)"]
        Concurrency["agrona-concurrency-tests\n(concurrency tests)"]
    end

    Agent -->|"depends on"| Core
    Benchmarks -->|"depends on"| Core
    Concurrency -->|"depends on"| Core

    %% Build & Config
    subgraph "Build & Configuration"
        GradleWrapper["Gradle Wrapper\n(gradlew, wrapper config)"]
        subgraph "buildSrc"
            UnsafeBytecode["UnsafeApiBytecodeGenerator"]
            UnsafeSource["UnsafeApiSourceGenerator"]
            UploadTask["SonatypeCentralPortalUploadRepositoryTask"]
        end
        BuildFiles["build.gradle\nsettings.gradle\nversion.txt\ngradle/libs.versions.toml"]
    end

    GradleWrapper -->|"executes"| UnsafeBytecode
    GradleWrapper -->|"executes"| UnsafeSource
    GradleWrapper -->|"executes"| UploadTask
    GradleWrapper -->|"configures & builds"| Core
    GradleWrapper -->|"configures & builds"| Agent
    GradleWrapper -->|"configures & builds"| Benchmarks
    GradleWrapper -->|"configures & builds"| Concurrency
    BuildFiles -->|applies| GradleWrapper

    %% CI/CD & Quality
    subgraph "CI/CD & Quality"
        CI_CI["CI Workflow\n(ci.yml)"]
        CI_CodeQL["CodeQL Workflow\n(codeql.yml)"]
        CI_Release["Release Workflow\n(release.yml)"]
        Checkstyle1["checkstyle.xml"]
        Checkstyle2["suppressions.xml"]
        PublishScript["publish_artifacts.sh"]
    end

    CI_CI -->|"triggers build"| GradleWrapper
    CI_CodeQL -->|"runs scans"| Core
    CI_Release -->|"publishes artifacts"| Maven
    Checkstyle1 -->|"enforced in"| CI_CI
    Checkstyle2 -->|"enforced in"| CI_CI
    PublishScript -->|"used by"| CI_Release

    %% External Systems
    subgraph "External Systems"
        GitHub["GitHub"]
        Maven["Maven Central"]
    end

    GitHub -->|push & PR events| CI_CI
    CI_Release -->|publishes to| Maven

    %% Consumer
    Consumer["Consumer Application"]
    Consumer -.->|"retrieve agrona"| Maven
    Consumer -.->|"attach agent at JVM startup"| Agent

    %% Classes
    classDef module fill:#D6E5FF,stroke:#0050B3
    classDef build fill:#FFF2CC,stroke:#B58900
    classDef external fill:#E0E0E0,stroke:#7D7D7D
    classDef ci fill:#FFE4CC,stroke:#DD6E00

    class Core,Agent,Benchmarks,Concurrency module
    class GradleWrapper,UnsafeBytecode,UnsafeSource,UploadTask,BuildFiles build
    class CI_CI,CI_CodeQL,CI_Release,Checkstyle1,Checkstyle2,PublishScript ci
    class GitHub,Maven,Consumer external

    %% Click Events
    click Core "https://github.com/aeron-io/agrona/tree/master/agrona/src/main/java/org/agrona"
    click Agent "https://github.com/aeron-io/agrona/blob/master/agrona-agent/src/main/java/org/agrona/agent/BufferAlignmentAgent.java"
    click Benchmarks "https://github.com/aeron-io/agrona/blob/master/agrona-benchmarks/src/main/java/org/agrona/concurrent/ClockBenchmark.java"
    click Concurrency "https://github.com/aeron-io/agrona/blob/master/agrona-concurrency-tests/src/main/java/org/agrona/concurrent/ManyToOneRingBufferTests.java"
    click UnsafeBytecode "https://github.com/aeron-io/agrona/blob/master/buildSrc/src/main/java/org/agrona/build/UnsafeApiBytecodeGenerator.java"
    click UnsafeSource "https://github.com/aeron-io/agrona/blob/master/buildSrc/src/main/java/org/agrona/build/UnsafeApiSourceGenerator.java"
    click UploadTask "https://github.com/aeron-io/agrona/blob/master/buildSrc/src/main/java/org/agrona/build/SonatypeCentralPortalUploadRepositoryTask.java"
    click GradleWrapper "https://github.com/aeron-io/agrona/tree/master/gradlew"
    click BuildFiles "https://github.com/aeron-io/agrona/blob/master/build.gradle"
    click CI_CI "https://github.com/aeron-io/agrona/blob/master/.github/workflows/ci.yml"
    click CI_CodeQL "https://github.com/aeron-io/agrona/blob/master/.github/workflows/codeql.yml"
    click CI_Release "https://github.com/aeron-io/agrona/blob/master/.github/workflows/release.yml"
    click Checkstyle1 "https://github.com/aeron-io/agrona/blob/master/config/checkstyle/checkstyle.xml"
    click Checkstyle2 "https://github.com/aeron-io/agrona/blob/master/config/checkstyle/suppressions.xml"
    click PublishScript "https://github.com/aeron-io/agrona/blob/master/publish_artifacts.sh"
```
