# aeron-io/aeron architecture

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

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

## Overview

##### Project Type and Purpose
- Aeron is a high-performance message transport framework supporting UDP unicast, UDP multicast, and IPC.
- It provides multi-language client libraries (Java, C, C++), a Media Driver that handles network and IPC I/O, an Archive module for durable recording/replay, and a Cluster module for Raft-based replicated state machines.

##### High-Level Modules (Top-Level Directories)
- aeron-client: language bindings and client-side Conductor logic
- aeron-driver: Media Driver implementation (network, IPC, threading, flow control)
- aeron-archive: persistent storage of streams (recording, replay)
- aeron-cluster: fault-tolerant cluster services using Raft consensus
- aeron-agent, aeron-annotations, aeron-test-support: support, tooling, logging agents, codegen, testing

##### Key Components
a. Client Application
- Language-specific API (Java/C/C++)
- ClientConductor (manages publications/subscriptions, ring buffers to Media Driver)
b. Media Driver
- IPC layer (shared memory ring buffers between client and driver)
- Network transport (UDP send/receive endpoints, flow/congestion control)
- Threading model (sender thread, receiver thread, conductor thread)
c. Archive Module
- ArchiveConductor (listens on control streams from clients)
- RecordingWriter (writes messages to file store)
- ReplaySession (reads recordings and publishes to clients)
d. Cluster Module
- ConsensusModule (leader election, log replication)
- ClusteredMediaDriver & ClusterBackup (integrate Media Driver with cluster state)
e. Storage and External Services
- File system for recordings (catalog, segment files)
- Optional monitoring or MBean endpoints

##### Relationships and Data Flows
- Media Driver → Sender Thread → UDP Socket → Remote Media Driver Receiver Thread → IPC Ring Buffer → Remote ClientConductor → Client API → Remote Client Application
- Archive: ClientConductor publishes control messages to Archive channels → ArchiveConductor reads those streams via Media Driver → RecordingWriter writes to disk
- Replay: ArchiveConductor reads from disk → ReplaySession publishes via Media Driver → ClientConductor receives via IPC → Client application
- Cluster: Clients submit messages to Cluster ingress via Media Driver; ConsensusModule replicates logs; egress messages flow back via Media Driver

##### Architectural Patterns and Principles
- Modular multi-language client–driver separation via IPC ring buffers
- Thread-per-role in Media Driver (conductor, sender, receiver) with lock-free queues
- Back-pressure and flow control loops in both IPC and network layers
- Extension points: custom CongestionControl, Authenticators, external NameResolver
- Archive and Cluster built on top of core transport, reusing Media Driver I/O

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        ClientApp["Client Application"]:::client
        AeronApi["Java API (Aeron.java)"]:::client
        ClientConductorJava["ClientConductor (Java)"]:::client
        ClientConductorC["ClientConductor (C)"]:::client
    end

    %% Media Driver Layer
    subgraph "Media Driver Layer"
        direction TB
        MediaDriverJava["MediaDriver (Java)"]:::driver
        MediaDriverNative["MediaDriver (C)"]:::driver
        DriverConductorJava["DriverConductor (Java)"]:::driver
        DriverConductorC["DriverConductor (C)"]:::driver
        subgraph "IPC Layer"
            direction TB
            IpcPubJava["IpcPublication (Java)"]:::driver
            IpcSubLinkJava["IpcSubscriptionLink (Java)"]:::driver
            IpcPubC["IpcPublication (C)"]:::driver
        end
        subgraph "Network Transport"
            direction TB
            UdpPoller["UdpTransportPoller (Java)"]:::driver
            DataDispatcher["DataPacketDispatcher (C)"]:::driver
            FlowControl["FlowControl (Java)"]:::driver
            UDPSender["Sender Thread"]:::driver
            UDPReceiver["Receiver Thread"]:::driver
        end
        ThreadingMode["ThreadingMode"]:::driver
    end

    %% Network
    subgraph "Network"
        direction TB
        UDPSocket["UDP Socket"]:::network
    end

    %% Archive Module
    subgraph "Archive Module"
        direction TB
        ArchiveConductor["ArchiveConductor"]:::persistence
        RecordingWriter["RecordingWriter"]:::persistence
        ReplaySession["ReplaySession"]:::persistence
        Catalog["Catalog"]:::persistence
    end

    %% Cluster Module
    subgraph "Cluster Module"
        direction TB
        ConsensusModule["ConsensusModule"]:::cluster
        ClusteredMediaDriver["ClusteredMediaDriver"]:::cluster
        ClusterBackup["ClusterBackup"]:::cluster
    end

    %% Storage
    subgraph "Storage"
        direction TB
        CatalogIndex["CatalogIndex"]:::persistence
        SegmentFiles["Segment Files"]:::persistence
    end

    %% Flows
    ClientApp -->|"uses"| AeronApi
    AeronApi -->|"invokes"| ClientConductorJava
    ClientConductorJava -->|"IPC"| IpcPubJava
    IpcPubJava -->|"shared memory"| DriverConductorJava
    DriverConductorJava -->|"dispatch"| UDPSender
    UDPSender -->|UDP| UDPSocket
    UDPSocket -->|UDP| UDPReceiver
    UDPReceiver -->|"to driver"| DataDispatcher
    DataDispatcher -->|"to IPC"| IpcSubLinkJava
    IpcSubLinkJava -->|"IPC"| ClientConductorJava
    ClientConductorJava -->|"delivers"| AeronApi
    AeronApi -->|"to"| ClientApp

    %% Archive flows
    ClientConductorJava -->|"control msgs"| ArchiveConductor
    ArchiveConductor -->|"writes"| RecordingWriter
    RecordingWriter -->|"file I/O"| CatalogIndex
    ReplaySession -->|"reads"| RecordingWriter
    ReplaySession -->|"publishes via"| UDPSender
    IpcSubLinkJava -->|"replay IPC"| ClientConductorJava

    %% Cluster flows
    AeronApi -->|"cluster ingress"| ClusteredMediaDriver
    ClusteredMediaDriver -->|"raft RPC"| ConsensusModule
    ConsensusModule -->|"replication"| ClusterBackup
    ConsensusModule -->|"egress"| UDPSender
    UDPSender -->|"to client"| IpcSubLinkJava

    %% Click Events
    click AeronApi "https://github.com/aeron-io/aeron/blob/master/aeron-client/src/main/java/io/aeron/Aeron.java"
    click ClientConductorJava "https://github.com/aeron-io/aeron/blob/master/aeron-client/src/main/java/io/aeron/ClientConductor.java"
    click ClientConductorC "https://github.com/aeron-io/aeron/blob/master/aeron-client/src/main/c/aeron_client_conductor.c"
    click MediaDriverJava "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/java/io/aeron/driver/MediaDriver.java"
    click MediaDriverNative "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/c/aeron_driver.c"
    click DriverConductorJava "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java"
    click DriverConductorC "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/c/aeron_driver_conductor.c"
    click IpcPubJava "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/java/io/aeron/driver/IpcPublication.java"
    click IpcPubC "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/c/aeron_ipc_publication.c"
    click IpcSubLinkJava "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/java/io/aeron/driver/IpcSubscriptionLink.java"
    click UdpPoller "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/java/io/aeron/driver/media/UdpTransportPoller.java"
    click DataDispatcher "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/c/aeron_data_packet_dispatcher.c"
    click FlowControl "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/java/io/aeron/driver/FlowControl.java"
    click ThreadingMode "https://github.com/aeron-io/aeron/blob/master/aeron-driver/src/main/java/io/aeron/driver/ThreadingMode.java"
    click ArchiveConductor "https://github.com/aeron-io/aeron/blob/master/aeron-archive/src/main/java/io/aeron/archive/ArchiveConductor.java"
    click RecordingWriter "https://github.com/aeron-io/aeron/blob/master/aeron-archive/src/main/java/io/aeron/archive/RecordingWriter.java"
    click ReplaySession "https://github.com/aeron-io/aeron/blob/master/aeron-archive/src/main/java/io/aeron/archive/ReplaySession.java"
    click Catalog "https://github.com/aeron-io/aeron/blob/master/aeron-archive/src/main/java/io/aeron/archive/Catalog.java"
    click ConsensusModule "https://github.com/aeron-io/aeron/blob/master/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java"
    click ClusteredMediaDriver "https://github.com/aeron-io/aeron/blob/master/aeron-cluster/src/main/java/io/aeron/cluster/ClusteredMediaDriver.java"
    click ClusterBackup "https://github.com/aeron-io/aeron/blob/master/aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackup.java"
    click CatalogIndex "https://github.com/aeron-io/aeron/blob/master/aeron-archive/src/main/java/io/aeron/archive/CatalogIndex.java"
    click SegmentFiles "https://github.com/aeron-io/aeron/blob/master/aeron-archive/src/main/resources/archive/aeron-archive-codecs.xml"

    %% Styles
    classDef client fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32;
    classDef driver fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
    classDef persistence fill:#fff3e0,stroke:#ef6c00,color:#e65100;
    classDef cluster fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c;
    classDef network fill:#eceff1,stroke:#546e7a,color:#37474f;
```
