# threedotslabs/watermill architecture

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

- Interactive diagram: https://gitdiagram.com/threedotslabs/watermill
- Repository: https://github.com/threedotslabs/watermill

## Overview

##### Project Type and Purpose
- Watermill is a Go library that enables developers to build event‐driven systems. It abstracts away the complexities of interacting with various Pub/Sub systems (such as Kafka, RabbitMQ, NATS, etc.) and provides advanced features like CQRS, event sourcing, middleware, and message routing.
- The project is not an end-user application but a library that provides interfaces and components to build distributed, scalable, and resilient messaging architectures.

##### Analysis of the File Structure
- Top-level directories such as “components”, “message”, “pubsub” and “internal” indicate modularization of functionalities:
- The “components” directory includes implementations of CQRS, delay mechanisms, fanin, forwarder, metrics, request/reply patterns, and requeuer modules.
- The “message” directory contains the core message logic, decorators, metadata handling, router and related middlewares. Inside “message/router/middleware”, you see multiple middleware implementations (e.g., circuit breaker, retry, timeout) that manage how messages are processed.
- The “pubsub” directory provides implementations or adapters for different Pub/Sub patterns (e.g. go-channel pattern).
- The “internal” packages hold publisher and subscriber implementations with tests, suggesting careful verification.
- There is an extensive “_examples” directory providing both “basic” examples and “real-world” scenarios, demonstrating different use cases, configurations, and integration patterns.
- Documentation and configuration files (like Docker Compose files, Makefiles, CI/CD workflows) reinforce that this project is intended for both library users and contributors, with a strong emphasis on testability and performance benchmarks.

##### Key Architecture Insights from the README
- The README emphasizes the core interface for message handling: a function that accepts a message and returns new messages (or an error).
- It outlines support for a variety of Pub/Sub systems – each provided as separate packages. This means the architecture must be open and extensible for new integrations.
- Watermill’s goals of flexibility, ease-of-use, and resiliency are achieved through modularization (plugins, middlewares, and separate components) and well-defined interfaces (Publisher and Subscriber).

##### Final Recommendations
- Be very detailed: each component’s role should be clear along with its relationship to other components.
- That labels are self-explanatory: include technical terms such as “CQRS”, “message decorator”, “bus”, etc.
- To represent the extensibility of the system: how additional Pub/Sub implementations can be plugged into the architecture.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library"
        Msg["Core Message Object"]:::core
        Pub["Publisher Interface"]:::interface
        Sub["Subscriber Interface"]:::interface
    end

    %% Components
    subgraph "Components"
        CQRS["CQRS Module"]:::component
        Delay["Delay Mechanism"]:::component
        Fanin["Fanin Module"]:::component
        Forwarder["Forwarder Module"]:::component
        Metrics["Metrics Module"]:::component
        ReqReply["Request/Reply Module"]:::component
        Requeuer["Requeuer Module"]:::component
    end

    %% Routing Layer
    subgraph "Routing"
        Router["Message Router"]:::router
        Middleware["Middleware Chain"]:::router
    end

    %% Adapters / External Integrations
    subgraph "Adapters/Integrations"
        Adapter["Pub/Sub Adapters"]:::adapter
    end

    %% Example Applications
    subgraph "Examples"
        Examples["Example Applications"]:::example
    end

    %% Message Flow
    Pub -->|"publish"| Middleware
    Middleware -->|"process"| Router
    Router -->|"deliver"| Sub

    %% Core object usage
    Pub -- "uses" --> Msg
    Sub -- "receives" --> Msg

    %% Components enhancing routing
    CQRS -.->|"enhances"| Router
    Delay -.->|"enhances"| Router
    Fanin -.->|"enhances"| Router
    Forwarder -.->|"enhances"| Router
    Metrics -.->|"enhances"| Router
    ReqReply -.->|"enhances"| Router
    Requeuer -.->|"enhances"| Router

    %% Pub/Sub Adapters integration
    Adapter -->|"integrates"| Pub
    Adapter -->|"integrates"| Sub

    %% Example applications interact with core interfaces
    Examples -.->|"triggers"| Pub
    Examples -.->|"triggers"| Sub

    %% Click Events
    click Msg "https://github.com/threedotslabs/watermill/blob/master/message/message.go"
    click Pub "https://github.com/threedotslabs/watermill/tree/master/internal/publisher"
    click Sub "https://github.com/threedotslabs/watermill/tree/master/internal/subscriber"
    click CQRS "https://github.com/threedotslabs/watermill/tree/master/components/cqrs"
    click Delay "https://github.com/threedotslabs/watermill/tree/master/components/delay"
    click Fanin "https://github.com/threedotslabs/watermill/tree/master/components/fanin"
    click Forwarder "https://github.com/threedotslabs/watermill/tree/master/components/forwarder"
    click Metrics "https://github.com/threedotslabs/watermill/tree/master/components/metrics"
    click ReqReply "https://github.com/threedotslabs/watermill/tree/master/components/requestreply"
    click Requeuer "https://github.com/threedotslabs/watermill/tree/master/components/requeuer"
    click Router "https://github.com/threedotslabs/watermill/tree/master/message/router"
    click Middleware "https://github.com/threedotslabs/watermill/tree/master/message/router/middleware"
    click Adapter "https://github.com/threedotslabs/watermill/tree/master/pubsub"
    click Examples "https://github.com/threedotslabs/watermill/tree/master/_examples"

    %% Styles
    classDef core fill:#a2d2ff,stroke:#1e90ff,stroke-width:2px;
    classDef interface fill:#ffc8dd,stroke:#ff6f91,stroke-width:2px;
    classDef component fill:#ffdfba,stroke:#ff9f1c,stroke-width:2px;
    classDef router fill:#caffbf,stroke:#57cc99,stroke-width:2px;
    classDef adapter fill:#ffadad,stroke:#ff6b6b,stroke-width:2px;
    classDef example fill:#d0f4de,stroke:#38b000,stroke-width:2px;
```
