# hivemq/hivemq-community-edition architecture

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

- Interactive diagram: https://gitdiagram.com/hivemq/hivemq-community-edition
- Repository: https://github.com/hivemq/hivemq-community-edition

## Overview

##### Project type and purpose
- HiveMQ CE is a Java-based, open-source, monolithic MQTT broker (server) implementing MQTT 3.x and 5.0.
- It can run standalone (distro or Docker), or be embedded via its Java API.

##### Key architectural components (derived from src/main/java packages and README)
A. Network Ingress Layer
- Listeners: TCP, TLS, WebSocket, WSS (src/main/java/com/hivemq/bootstrap/netty/initializer)
- Netty event-loop and pipeline (ChannelInitializerFactory, ChannelDependencies, ExceptionHandler)

B. Protocol Codec Layer
- MQTT decoders and encoders for MQTT 3.x & 5.0 (src/main/java/com/hivemq/codec/decoder & encoder)

C. MQTT Core Handler Layer
- Handlers for CONNECT, CONNACK, PUBLISH, SUBSCRIBE, etc. (src/main/java/com/hivemq/mqtt/handler)
- Internal services: PublishService, PublishDistributor, SubscribeService, etc.

D. Session & Subscription Management
- ClientSessionPersistence, SubscriptionStore, TopicTree (src/main/java/com/hivemq/persistence & mqtt/topic/tree)

E. Persistence Layer
- In-memory, File, Xodus, RocksDB backends (configured via Guice PersistenceModules)
- Entities: client queues, retained messages, payloads

F. Extension Framework
- ExtensionLoader, ClassServiceLoader, ExtensionBootstrap
- Extension SDK: interceptors, authenticators, authorizers, client initializers (com.hivemq/extensions)

G. Configuration & Dependency Injection
- Reads XML config, merges environment vars/system props (src/main/java/com/hivemq/configuration)
- Guice DI modules: bootstrap, netty, configuration, persistence, mqtt, extensions, security, metrics, throttling

H. Observability & Lifecycle
- Metrics (JMX, internal gauges), diagnostic mode, logging (SLF4J/Logback)
- Startup/shutdown hooks, health verification

I. Embedded Mode API
- EmbeddedHiveMQBuilder and EmbeddedExtensionBuilder for programmatic integration

##### Relationships and data flows
1) Clients → Network Listeners → Netty Pipeline
2) Byte streams → MQTTDecoder → MQTTMessage objects
3) MQTTMessage → CoreHandlers → InternalServices
– CONNECT → SessionManager
– PUBLISH → PublishService + Persist/PersistedStores
– SUBSCRIBE → TopicTree lookup → Distribution
4) CoreHandlers fire extension events (interceptors, auth) → ExtensionFramework
5) Persistence I/O abstracts to multiple backends via DI
6) Responses traverse reverse path: CoreHandlers → MQTTEncoder → Netty → Client
7) ConfigurationService and DI bootstrap assemble modules at startup
8) Metrics & Diagnostic modules observe internal events and expose via JMX/log

##### Architectural patterns and principles
- Modular layering (Network → Codec → Core → Persistence → Extensions)
- IoC/DI via Google Guice for pluggability and testability
- Event-driven, non-blocking I/O (Netty)
- Plugin/Extension classloader isolation
- Separation of concerns: protocol vs. business logic vs. storage vs. extensions

##### Technologies and frameworks
- Netty (networking)
- Guice (DI)
- Xodus / RocksDB / File / In-memory (persistence)
- SLF4J + Logback (logging)
- JMX (metrics)
- Java 11+
- Docker (distribution)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    MQTTClients["MQTT Clients"]:::external
    DockerHost["Docker Embed/API"]:::external

    %% Network Layer
    subgraph "Network Ingress Layer"
        style NetworkLayer fill:#AED6F1,stroke:#21618C,stroke-width:2px
        TcpInit["TcpChannelInitializer"]:::network
        WebsocketInit["WebsocketChannelInitializer"]:::network
        ChannelFactory["ChannelInitializerFactory"]:::network
        ChannelDeps["ChannelDependencies"]:::network
        ExceptionHandler["ExceptionHandler"]:::network
    end

    %% Codec Layer
    subgraph "Protocol Codec Layer"
        style CodecLayer fill:#F5B041,stroke:#B9770E,stroke-width:2px
        MQTTDecoder["MQTTDecoder"]:::codec
        MQTTEncoder["MQTTEncoder"]:::codec
    end

    %% Core Handler Layer
    subgraph "MQTT Core Handler Layer"
        style CoreLayer fill:#ABEBC6,stroke:#1D8348,stroke-width:2px
        CONNECTHandler["CONNECT Handler"]:::core
        PUBLISHHandler["PUBLISH Handler"]:::core
        SUBSCRIBEHandler["SUBSCRIBE Handler"]:::core
        PublishService["PublishServiceImpl"]:::core
        PublishDistributor["PublishDistributorImpl"]:::core
    end

    %% Session & Subscription Management
    subgraph "Session & Subscription Management"
        style SessionLayer fill:#F9E79F,stroke:#B7950B,stroke-width:2px
        ClientSessionStore["ClientSessionPersistenceImpl"]:::session
        TopicTree["LocalTopicTree"]:::session
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        style PersistenceLayer fill:#D2B4DE,stroke:#6C3483,stroke-width:2px
        AbstractPersistence["AbstractPersistence"]:::persistence
        FilePersistence["FilePersistence"]:::persistence
        MemoryModule["LocalPersistenceMemoryModule"]:::persistence
        RocksDBModule["LocalPersistenceRocksDBModule"]:::persistence
        RetainedStore["RetainedMessageStore"]:::persistence
        PayloadStore["PayloadStore"]:::persistence
    end

    %% Extension Framework
    subgraph "Extension Framework"
        style ExtLayer fill:#F8C471,stroke:#B9770E,stroke-width:2px
        ExtensionLoader["ExtensionLoader"]:::extension
        ExtensionBootstrap["ExtensionBootstrapImpl"]:::extension
        ClassServiceLoader["ClassServiceLoader"]:::extension
    end

    %% Configuration & DI
    subgraph "Configuration & Dependency Injection"
        style ConfigLayer fill:#D5D8DC,stroke:#566573,stroke-width:2px
        ConfigBootstrap["ConfigurationBootstrap"]:::config
        ConfigModule["ConfigurationModule"]:::config
        MainModule["HiveMQMainModule"]:::config
    end

    %% Observability & Lifecycle
    subgraph "Observability & Lifecycle"
        style ObsLayer fill:#FCF3CF,stroke:#B7950B,stroke-width:2px
        Metrics["HiveMQMetrics"]:::obs
        EventLog["EventLog"]:::obs
        Diagnostic["DiagnosticMode"]:::obs
        Lifecycle["LifecycleRegistry"]:::obs
    end

    %% Embedded API
    EmbeddedAPI["EmbeddedHiveMQBuilder"]:::embedded

    %% Security / TLS
    SSL["SslContextFactory"]:::security

    %% Data Flows
    MQTTClients -->|TCP/WS| TcpInit
    TcpInit -->|build pipeline| ChannelFactory
    ChannelFactory --> ChannelDeps
    ChannelDeps --> ExceptionHandler
    ExceptionHandler --> MQTTDecoder
    MQTTDecoder --> CONNECTHandler
    CONNECTHandler --> ClientSessionStore
    CONNECTHandler --> ExtensionLoader
    PUBLISHHandler --> PublishService
    PublishService --> RetainedStore
    PublishService --> PayloadStore
    PublishDistributor --> TopicTree
    SUBSCRIBEHandler --> TopicTree
    CONNECTHandler -->|events| ExtensionBootstrap
    ExtensionBootstrap --> ClassServiceLoader
    CONNECTHandler --> MQTTEncoder
    MQTTEncoder -->|outbound| ExceptionHandler
    MQTTEncoder --> MQTTClients

    %% DI & Startup
    ConfigBootstrap --> ConfigModule
    ConfigModule --> MainModule
    MainModule --> NetworkLayer
    MainModule --> CodecLayer
    MainModule --> CoreLayer
    MainModule --> PersistenceLayer
    MainModule --> ExtLayer
    MainModule --> ObsLayer

    %% Observability flows
    CoreLayer --> Metrics
    CoreLayer --> EventLog
    CoreLayer --> Diagnostic
    CoreLayer --> Lifecycle

    DockerHost --> EmbeddedAPI

    %% Click Events
    click TcpInit "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/bootstrap/netty/initializer/TcpChannelInitializer.java"
    click WebsocketInit "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/bootstrap/netty/initializer/WebsocketChannelInitializer.java"
    click ChannelFactory "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/bootstrap/netty/ChannelInitializerFactory.java"
    click ChannelDeps "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/bootstrap/netty/ChannelDependencies.java"
    click ExceptionHandler "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/bootstrap/netty/initializer/ExceptionHandler.java"
    click MQTTDecoder "https://github.com/hivemq/hivemq-community-edition/tree/master/src/main/java/com/hivemq/codec/decoder"
    click MQTTEncoder "https://github.com/hivemq/hivemq-community-edition/tree/master/src/main/java/com/hivemq/codec/encoder"
    click CONNECTHandler "https://github.com/hivemq/hivemq-community-edition/tree/master/src/main/java/com/hivemq/mqtt/handler"
    click PublishService "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/mqtt/services/PublishServiceImpl.java"
    click PublishDistributor "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/mqtt/services/PublishDistributorImpl.java"
    click ClientSessionStore "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/persistence/clientsession/ClientSessionPersistenceImpl.java"
    click TopicTree "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/mqtt/topic/tree/LocalTopicTree.java"
    click AbstractPersistence "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/persistence/AbstractPersistence.java"
    click FilePersistence "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/persistence/FilePersistence.java"
    click MemoryModule "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/persistence/ioc/LocalPersistenceMemoryModule.java"
    click RocksDBModule "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/persistence/ioc/LocalPersistenceRocksDBModule.java"
    click ExtensionLoader "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/extensions/ExtensionLoader.java"
    click ExtensionBootstrap "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/extensions/ExtensionBootstrapImpl.java"
    click ClassServiceLoader "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/extensions/ClassServiceLoader.java"
    click ConfigBootstrap "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/configuration/ConfigurationBootstrap.java"
    click ConfigModule "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/configuration/ConfigurationModule.java"
    click MainModule "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/bootstrap/ioc/HiveMQMainModule.java"
    click Metrics "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/metrics/HiveMQMetrics.java"
    click EventLog "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/logging/EventLog.java"
    click Diagnostic "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/diagnostic/DiagnosticMode.java"
    click Lifecycle "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/lifecycle/LifecycleRegistry.java"
    click EmbeddedAPI "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/embedded/EmbeddedHiveMQBuilder.java"
    click SSL "https://github.com/hivemq/hivemq-community-edition/blob/master/src/main/java/com/hivemq/security/ssl/SslContextFactory.java"

    %% Classes
    classDef external fill:#D6EAF8,stroke:#1B4F72
    classDef network fill:#AED6F1,stroke:#21618C
    classDef codec fill:#F5B041,stroke:#B9770E
    classDef core fill:#ABEBC6,stroke:#1D8348
    classDef session fill:#F9E79F,stroke:#B7950B
    classDef persistence fill:#D2B4DE,stroke:#6C3483
    classDef extension fill:#F8C471,stroke:#B9770E
    classDef config fill:#D5D8DC,stroke:#566573
    classDef obs fill:#FCF3CF,stroke:#B7950B
    classDef embedded fill:#FADBD8,stroke:#922B21
    classDef security fill:#E8DAEF,stroke:#6C3483
```
