# zeromq/libzmq architecture

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

- Interactive diagram: https://gitdiagram.com/zeromq/libzmq
- Repository: https://github.com/zeromq/libzmq

## Overview

##### Main Components
- Library Core: At the heart is the ZeroMQ core, which includes context management (src/ctx.cpp, src/ctx.hpp), socket abstractions (src/socket_base.cpp, src/pub.cpp, src/sub.cpp, etc.), and message handling (src/msg.cpp, src/msg.hpp).
- Transport Mechanisms: There are separate modules for different transport protocols such as TCP (src/tcp.cpp, src/tcp_listener.cpp, etc.), IPC, inproc, tipc, and even more specialized transports (e.g., PGM in src/pgm_* files, VMCI in src/vmci.cpp files and WebSockets via src/ws_* files).
- I/O and Polling: Several files address IO thread management and polling mechanisms (src/io_thread.cpp, src/poll.cpp, src/poller.hpp, src/epoll.cpp, src/select.cpp, etc.).
- Security and Authentication: Components for various security mechanisms (curve, plain, GSSAPI) are evident from files like src/curve_client.cpp, src/curve_server.cpp, src/gssapi_client.cpp, src/gssapi_server.cpp.
- Build and Configuration Infrastructure: A large part of the file tree (directories like builds, packaging, tests, and configuration files such as configure.ac, CMakeLists.txt, Makefile.am) suggests a robust build system that supports different platforms and test scenarios.

##### Relationships and Interactions
- The core component provides the API that applications call; it internally uses the I/O components, the different transport handlers, and security mechanisms.
- Connections flow from the application’s usage of the ZeroMQ API (seen in include/zmq.h) through to the context and socket implementations.
- Each transport mechanism (TCP, IPC, etc.) acts as an adapter inside the core engine, handling network communication and interfacing with OS-level I/O.
- The polling and event-loop modules coordinate I/O events and message distribution among sockets concurrently.

##### Architectural Patterns & Design Principles
- Modular Design: The source directory is clearly divided into separate components (sockets, transports, security, polling), each encapsulated in its own file/module.
- Abstraction and Extensibility: By offering a generic messaging API (with files in include/ and src/), ZeroMQ allows different transport strategies to be plugged in.
- Asynchronous and Non-blocking I/O: The design inherently supports asynchronous operations with multiple building blocks (e.g., the IO thread, pollers, and messaging queues).

##### Additional Notes
- Refer to the README for supported platforms and deployment notes – you might add a note indicating that the build system supports multiple platforms (Windows, Linux, OSX, etc.), which is part of its versatility.
- Detail the internal API boundaries – for example, delineate between public API (in include/zmq.h) and internal implementations in src/.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Application (Uses ZeroMQ API)"]:::public

    subgraph "Library Core"
        B["Core (Context & Messaging)"]:::core
    end

    subgraph "Socket Abstractions"
        C["Sockets (pub/sub, req/rep, router/dealer)"]:::socket
    end

    subgraph "I/O and Polling"
        D["I/O & Polling (Event Loop, Pollers)"]:::io
    end

    subgraph "Transport Mechanisms"
        subgraph "TCP"
            E1["TCP Module"]:::transport
        end
        subgraph "IPC/Inproc"
            E2["IPC/Inproc Module"]:::transport
        end
        subgraph "Specialized Transports"
            E3_PGM["PGM Module"]:::specialized
            E3_VMCI["VMCI Module"]:::specialized
            E3_WS["WebSockets Module"]:::specialized
        end
    end

    subgraph "Security"
        F["Security (Curve, Plain, GSSAPI)"]:::security
    end

    subgraph "Build & Configuration"
        G["Build & Config"]:::build
    end

    %% Relationships
    A -->|"calls"| B
    B -->|"utilizes"| C
    B -->|"manages"| D
    B -->|"handles"| E1
    B -->|"handles"| E2
    B -->|"handles"| E3_PGM
    B -->|"handles"| E3_VMCI
    B -->|"handles"| E3_WS
    B -->|"integrates"| F
    G -->|"builds"| B

    %% Click Events
    click B "https://github.com/zeromq/libzmq/blob/master/src/ctx.cpp"
    click C "https://github.com/zeromq/libzmq/blob/master/src/pub.cpp"
    click D "https://github.com/zeromq/libzmq/blob/master/src/io_thread.cpp"
    click E1 "https://github.com/zeromq/libzmq/blob/master/src/tcp.cpp"
    click E2 "https://github.com/zeromq/libzmq/blob/master/src/ipc_address.cpp"
    click E3_PGM "https://github.com/zeromq/libzmq/blob/master/src/pgm_receiver.cpp"
    click E3_VMCI "https://github.com/zeromq/libzmq/blob/master/src/vmci.cpp"
    click E3_WS "https://github.com/zeromq/libzmq/blob/master/src/ws_address.cpp"
    click F "https://github.com/zeromq/libzmq/blob/master/src/curve_client.cpp"
    click G "https://github.com/zeromq/libzmq/blob/master/configure.ac"

    %% Styles
    classDef public fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef core fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef socket fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef io fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef transport fill:#ffa07a,stroke:#333,stroke-width:2px;
    classDef specialized fill:#ffdab9,stroke:#333,stroke-width:2px;
    classDef security fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef build fill:#f0e68c,stroke:#333,stroke-width:2px;
```
