# amqp/rhea architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Node.js library for AMQP 1.0 clients and servers.
- It is not a standalone application, but a modular, event-driven framework that users embed in their own services or scripts.
- Key use cases: publish/subscribe, request/response, durable subscriptions, TLS/SASL security, reconnection logic, WebSocket transport.

##### File-Structure Analysis
- Top‐level:
– lib/: core implementation modules (connection, session, link, transport, message, sasl, ws, etc.)
– dist/: browserified and UMD bundles for frontend usage
– examples/: sample scripts demonstrating various AMQP patterns and transports (direct, brokered, TLS, SASL, WebSockets, reconnect)
– test/: TypeScript tests covering behavior of connections, sessions, SASL, TLS, utility functions
– typings/: TypeScript declaration files for each core module
– package.json, tsconfig.json, Makefile, CI config (GitHub Actions)
- Architectural clues:
– Modular core in lib/ organized by AMQP concepts (Container → Connection → Session → Sender/Receiver → Message/Delivery)
– Transport abstractions (TCP vs TLS vs WebSocket) in transport.js and ws.js
– Event-driven design: every core object extends EventEmitter

##### Key Architectural Insights from README
- Five core object types: Container, Connection, Session, Receiver, Sender
- Two auxiliary types: Message, Delivery
- Container is the root; it spawns connections (client or server) over TCP/TLS/WebSocket
- Each Connection can have one or more Sessions
- Each Session manages links (Sender/Receiver)
- Messages flow over Sender/Receiver links; events bubble up from link → session → connection → container

##### Components
a. Core Library Layers (lib/)
– Container module
– Connection module (socket/tls wrapper)
– Session module
– Link modules: Sender, Receiver
– Protocol internals: frames.js, endpoint.js, filter.js, terminus.js, types.js, util.js
– SASL module for authentication
– Transport modules: transport.js (TCP/TLS), ws.js (WebSocket)
b. External Dependencies & Runtimes
– Node.js runtime
– debug logger module
– ‘ws’ module for WebSocket support
– AMQP broker (e.g. ActiveMQ, Qpid, RabbitMQ) or direct peer for brokerless messaging
– Browser environment (via UMD dist bundle) for web clients
c. Example Applications (examples/)
– Scripts that instantiate Container, open connections, send/receive messages
– Variations showing TLS, SASL, durable subscriptions, selectors, reconnection, WebSockets

##### Relationships and Data‐flow
- Transports: TCP/TLS link under Connection, WebSocket link variant
- Message objects flowing along Sender→Receiver paths; Delivery acknowledgements flowing back

##### Architectural Patterns & Principles
- Event-driven / reactive: illustrate EventEmitter propagation chain
- Layered protocol stack: application API → framing & AMQP logic → transport
- Pluggable transport (TCP vs TLS vs WebSocket)
- Modular design with clear separation of concerns (connection management, security, messaging)

## Diagram (Mermaid)

```mermaid
graph TB

  subgraph "Application Layer"
    User["User Code (API)"]:::external
    Examples["Example Apps"]:::examples
  end

  subgraph "Core Library (lib/)"
    Container["Container"]:::core
    Connection["Connection (TCP/TLS/WS)"]:::core
    Session["Session"]:::core
    Sender["Sender Link"]:::core
    Receiver["Receiver Link"]:::core
    Message["Message"]:::core

    subgraph "Protocol Internals"
      Frames["frames.js"]:::protocol
      Endpoint["endpoint.js"]:::protocol
      Filter["filter.js"]:::protocol
      Terminus["terminus.js"]:::protocol
      Types["types.js"]:::protocol
      Util["util.js"]:::protocol
      EventTypes["eventTypes.js"]:::protocol
      Errors["errors.js"]:::protocol
      Log["log.js"]:::protocol
    end

    SASL["SASL Auth"]:::security
    Transport["Transport (TCP/TLS)"]:::transport
    WS["WebSocket Transport"]:::transport
  end

  subgraph "Runtimes & External"
    NodeJS["Node.js Runtime"]:::external
    Debug["debug Logger"]:::external
    WSmod["ws Module"]:::external
    Broker["AMQP Broker"]:::external
    Browser["Browser Env (UMD)"]:::external
  end

  subgraph "Distribution & Types"
    Dist1["dist/rhea.js"]:::dist
    Dist2["dist/rhea-umd.js"]:::dist
    Typings["typings/*.d.ts"]:::typings
  end

  subgraph "Tests"
    Tests["test/*.ts"]:::tests
  end

  %% Relationships
  Examples -->|"uses API"| User
  User -->|"creates"| Container
  Container -->|"spawns"| Connection
  Connection -->|"opens"| Session
  Session -->|"adds link"| Sender
  Session -->|"adds link"| Receiver
  Sender -->|"sends Message"| Broker
  Broker -->|"delivers to"| Receiver
  Receiver -->|"event up"| Container

  Connection -->|"auth via"| SASL
  Connection -->|"uses"| Transport
  Connection -->|"uses"| WS

  Transport -->|"runs on"| NodeJS
  WS -->|"requires"| WSmod
  NodeJS -->|"logs via"| Debug
  Browser -->|"loads"| Dist1
  Browser -->|"loads"| Dist2
  User -->|"types from"| Typings
  Tests -->|"validate"| Container
  Tests -->|"validate"| Connection
  Tests -->|"validate"| Session
  Tests -->|"validate"| SASL

  %% Protocol internals usage
  Connection --> Frames
  Connection --> Endpoint
  Session --> Filter
  Session --> Terminus
  Sender --> Types
  Receiver --> Types
  Message --> Util
  Container --> EventTypes
  Container --> Errors
  Container --> Log

  %% Click Events
  click Container "https://github.com/amqp/rhea/blob/main/lib/container.js"
  click Connection "https://github.com/amqp/rhea/blob/main/lib/connection.js"
  click Session "https://github.com/amqp/rhea/blob/main/lib/session.js"
  click Sender "https://github.com/amqp/rhea/blob/main/lib/link.js"
  click Receiver "https://github.com/amqp/rhea/blob/main/lib/link.js"
  click Message "https://github.com/amqp/rhea/blob/main/lib/message.js"
  click Frames "https://github.com/amqp/rhea/blob/main/lib/frames.js"
  click Endpoint "https://github.com/amqp/rhea/blob/main/lib/endpoint.js"
  click Filter "https://github.com/amqp/rhea/blob/main/lib/filter.js"
  click Terminus "https://github.com/amqp/rhea/blob/main/lib/terminus.js"
  click Types "https://github.com/amqp/rhea/blob/main/lib/types.js"
  click Util "https://github.com/amqp/rhea/blob/main/lib/util.js"
  click EventTypes "https://github.com/amqp/rhea/blob/main/lib/eventTypes.js"
  click Errors "https://github.com/amqp/rhea/blob/main/lib/errors.js"
  click Log "https://github.com/amqp/rhea/blob/main/lib/log.js"
  click SASL "https://github.com/amqp/rhea/blob/main/lib/sasl.js"
  click Transport "https://github.com/amqp/rhea/blob/main/lib/transport.js"
  click WS "https://github.com/amqp/rhea/blob/main/lib/ws.js"
  click Dist1 "https://github.com/amqp/rhea/blob/main/dist/rhea.js"
  click Dist2 "https://github.com/amqp/rhea/blob/main/dist/rhea-umd.js"
  click Examples "https://github.com/amqp/rhea/tree/main/examples/"
  click Typings "https://github.com/amqp/rhea/tree/main/typings/"

  %% Styles
  classDef core fill:#AED6F1,stroke:#2980B9,color:#1B2631
  classDef transport fill:#A9DFBF,stroke:#239B56,color:#1B2631
  classDef protocol fill:#F9E79F,stroke:#B7950B,color:#1B2631
  classDef security fill:#F5B7B1,stroke:#CB4335,color:#1B2631
  classDef external fill:#D2B4DE,stroke:#7D3C98,color:#1B2631
  classDef examples fill:#E8DAEF,stroke:#6C3483,color:#1B2631
  classDef dist fill:#FDEBD0,stroke:#D68910,color:#1B2631
  classDef typings fill:#D6EAF8,stroke:#3498DB,color:#1B2631
  classDef tests fill:#FADBD8,stroke:#C0392B,color:#1B2631
```
