# copernicamarketingsoftware/amqp-cpp architecture

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

- Interactive diagram: https://gitdiagram.com/copernicamarketingsoftware/amqp-cpp
- Repository: https://github.com/copernicamarketingsoftware/amqp-cpp

## Overview

This project is a C++ library (“AMQP-CPP”) designed for asynchronous communication with a RabbitMQ broker by handling the AMQP protocol. Its purpose is to provide a low-level, non-blocking API that allows the user to parse, generate, and manage AMQP frames, while leaving the actual network I/O to custom or provided network modules. The architecture is layered and modular, and it is structured around a clear separation between protocol handling and I/O abstraction.

##### Main Components
- Core AMQP Engine – This is the heart of the library. It includes the central classes like Connection, Channel, Frame handling, and Deferred objects that manage asynchronous operations.
- I/O / Transport Abstraction – This layer consists of the abstract interfaces (ConnectionHandler and TcpHandler) that leave all socket creation and I/O management to the application (or to one of the provided TCP modules).
- Linux-specific TCP Module – Located under include/amqpcpp/linux_tcp and src/linux_tcp, this module implements a complete TCP (and TLS) handler for Linux. It encapsulates all network-specific calls (including use of pthread, dl, and openssl) used if the user opts for a built-in connection.
- Event Loop Integration – The library supports multiple external event loops. Samples in the examples/ directory demonstrate integration with libev, libuv, libevent, and even Boost.Asio. These “handler” implementations (e.g., LibEvHandler, LibUvHandler) wrap the TcpHandler interface so that the AMQP-CPP library can integrate with asynchronous event loops without blocking.
- Build and Examples – While not part of the runtime architecture, the build files (CMakeLists.txt, Makefile, etc.) and example source code provide insight into how the overall project is structured and how it is expected to interact with client applications.

##### Relationships and Interactions
- The client application uses the public API (e.g., by instantiating a Connection or TcpConnection and then creating Channels to interact with RabbitMQ) via connection handlers.
- The Core AMQP Engine parses incoming data into frames and handles outgoing data via callbacks installed by the user’s implementation of the ConnectionHandler/TcpHandler.
- The I/O/Transport Abstraction layer connects the core engine to any network/socket implementation. If using the built-in TCP module, then the Linux-specific classes handle connection setup and (optionally) TLS secure connections.
- In case of event loop integration, the TcpHandler’s monitor() function is implemented by one of the provided handler classes (for example, using libev) so that the AMQP library can be integrated seamlessly into the main event loop.
- Deferred objects in the core (returned by methods such as declareQueue() or publish()) manage asynchronous call chains and deliver success/error callbacks, which are propagated to the application.

##### Architectural Patterns and Design Principles
- Layered Architecture – A clear separation exists between the AMQP protocol handling (core) and the I/O (network abstraction) layer.
- Asynchronous, Non-blocking Design – The entire API is designed to be event-driven, relying on callbacks (onSuccess, onError, onAck, etc.) with deferred operations to avoid blocking the main thread.
- Abstraction and Flexibility – The project makes heavy use of abstraction (e.g., ConnectionHandler/TcpHandler interfaces) to allow users to plug in their own network mechanisms or event loops. This decoupling enhances portability.
- Modular Integration – Several optional modules (e.g., the TCP module, TLS support, event loop integrations) can be composed based on the deployment scenario.

##### Relevant Technologies, Frameworks, or Libraries
- C++17 – The library uses modern C++ features.
- OpenSSL – For handling TLS/SSL secure connections (dynamic linking is supported as well).
- pthread and dynamic loading (dl) – Used specifically by the TCP module for Linux.
- External event libraries – Examples are provided for libev, libuv, libevent, and Boost.Asio.
- Build Tools – The project supports both CMake and Make (the latter is Linux-only).

##### Specific Elements
– From the Application invoking AMQP operations → to the Connection/Channel layer → into the Core Protocol Engine.
– Outgoing frames get handed off to the I/O layer via the ConnectionHandler, eventually triggering low-level network operations.
– Incoming network data is parsed by the Core Engine, with callbacks routed back to the application via Deferred objects.
– Core library components versus network modules.
– Interfaces (abstract classes) versus concrete implementations.
– Optional integration layers (e.g., TCP module vs. custom I/O).
- “build/configuration” nodes (e.g., CMake, Makefiles) to indicate how the library is compiled with specific flags (like with or without the Linux TCP module).

– A top layer illustrating how client applications interact with the AMQP API.
– Intermediate layers that segment protocol handling (connection, channel, frame parsing) from the I/O abstraction (ConnectionHandler/TcpHandler).
– Lower-level modules that detail the support for TCP, TLS, and event loop integration.

This level of detail will ensure both the flexibility and robustness of AMQP-CPP’s layered design is effectively communicated.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer
    Client["Client Application"]:::client
    API["Connection/Channel Abstraction"]:::client

    Client -->|"invokes"| API

    %% AMQP Core Engine Subgraph
    subgraph "AMQP Core Engine"
        Core_Conn["Connection"]:::core
        Core_Ch["Channel"]:::core
        Core_Frame["Frame Handling"]:::core
        Core_Deferred["Deferred Objects"]:::core
        Core_Impl["Implementation (ConnImpl)"]:::core
        Core_Conn -->|"creates"| Core_Ch
        Core_Ch -->|"processes"| Core_Frame
        Core_Frame -->|"manages"| Core_Deferred
        Core_Deferred -->|"uses"| Core_Impl
    end

    API -->|"utilizes"| Core_Conn
    Core_Deferred -->|"callback"| Client

    %% I/O / Transport Abstraction Subgraph
    subgraph "I/O / Transport Abstraction"
        IO_Handler["ConnectionHandler Interface"]:::io
        IO_TCPParent["TCP Parent Interface"]:::io
        IO_TCPHandler["TCP Handler Interface"]:::io
        IO_Handler -->|"implements"| IO_TCPParent
        IO_TCPParent -->|"relies on"| IO_TCPHandler
    end

    Core_Frame -->|"sends frame"| IO_Handler

    %% Linux-specific TCP Module Subgraph
    subgraph "Linux-specific TCP Module"
        Linux_TCP_Conn["TCP Connection"]:::io
        Linux_TCP_Ch["TCP Channel"]:::io
        Linux_TCP_Def["TCP Defines"]:::io
        Linux_TCP_Src["TCP/TLS Source Files"]:::io
    end

    IO_TCPHandler -->|"uses"| Linux_TCP_Conn

    %% Event Loop Integration Subgraph
    subgraph "Event Loop Integration"
        EV_Handler["LibEv Handler"]:::event
        UV_Handler["LibUv Handler"]:::event
        LE_Handler["LibEvent Handler"]:::event
        Asio_Handler["Boost.Asio Handler"]:::event
        EV_Examples["Event Loop Examples"]:::event
        EV_Handler ---|"wraps"| IO_Handler
    end

    IO_Handler ---|"monitors"| EV_Handler

    %% Build and Examples Subgraph
    subgraph "Build and Examples"
        Build_Config["Build Configurations"]:::build
        Ex_Code["Example Source Code"]:::build
    end

    Client ---|"refers to"| Ex_Code

    %% Click Events for Core AMQP Engine
    click Core_Conn "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/connection.h"
    click Core_Ch "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/channel.h"
    click Core_Frame "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/frame.h"
    click Core_Deferred "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/deferred.h"
    click Core_Impl "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/src/connectionimpl.cpp"

    %% Click Events for I/O / Transport Abstraction
    click IO_Handler "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/connectionhandler.h"
    click IO_TCPParent "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/linux_tcp/tcpparent.h"
    click IO_TCPHandler "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/linux_tcp/tcphandler.h"

    %% Click Events for Linux-specific TCP Module
    click Linux_TCP_Conn "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/linux_tcp/tcpconnection.h"
    click Linux_TCP_Ch "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/linux_tcp/tcpchannel.h"
    click Linux_TCP_Def "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/linux_tcp/tcpdefines.h"
    click Linux_TCP_Src "https://github.com/copernicamarketingsoftware/amqp-cpp/tree/master/src/linux_tcp/"

    %% Click Events for Event Loop Integration
    click EV_Handler "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/libev.h"
    click UV_Handler "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/libuv.h"
    click LE_Handler "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/libevent.h"
    click Asio_Handler "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/include/amqpcpp/libboostasio.h"
    click EV_Examples "https://github.com/copernicamarketingsoftware/amqp-cpp/tree/master/examples/"

    %% Click Events for Build and Examples
    click Build_Config "https://github.com/copernicamarketingsoftware/amqp-cpp/blob/master/CMakeLists.txt"
    click Ex_Code "https://github.com/copernicamarketingsoftware/amqp-cpp/tree/master/examples/"

    %% Styles
    classDef client fill:#C7F9CC,stroke:#333,stroke-width:2px;
    classDef core fill:#FFC4C4,stroke:#900,stroke-width:2px;
    classDef io fill:#C4D7FF,stroke:#003,stroke-width:2px;
    classDef event fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef build fill:#FFFACD,stroke:#333,stroke-width:2px;
```
