# dunglas/mercure architecture

> Architecture diagram of the GitHub repository dunglas/mercure, 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/dunglas/mercure
- Repository: https://github.com/dunglas/mercure

## Overview

##### Main Components
- Hub Server: At the core is the Mercure hub, which handles incoming publish and subscribe requests. This component includes the Go code (files like cmd/mercure/main.go, handler.go, publish.go, subscribe.go, event.go, and several test files) that implement the protocol logic.
- Publisher/Subscriber Interfaces: Represent the two main “client types” that interact with the hub. Publishers send updates that need to be pushed out; Subscribers receive real‑time updates.
- Authorization & JWT Mechanism: There are files such as authorization.go, jwtkeyfunc.go, and related tests that indicate built‑in JWT handling and authorization logic. This module validates incoming requests and ensures that only the proper clients can publish or subscribe.
- Transport & Communication: Components like transport.go, local.go, and specialized modules under the caddy/ directory (plus Caddyfile and demo configurations) suggest that there is integration with a web server (like Caddy) for handling HTTP/2 and other transport protocols.
- Configuration & Deployment: The presence of Dockerfiles, Kubernetes Helm charts (in the charts/mercure and examples/chat/chart directories), and CI/CD workflows in .github/workflows highlights that deployment and scalable configuration are an integral part of the system.
- Ancillary Components: Include additional parts like metrics (metrics.go), logging (log.go), version handling (common/version.go), and conformance tests to illustrate the robustness of the hub.

##### Lay Out the Relationships & Data Flow
- Clients: Have separate blocks for “Publisher Clients” and “Subscriber Clients” that send requests to the hub.
- Caddy Server / Reverse Proxy: Include a node for Caddy (with its dedicated directory and configuration files) that acts as a gateway or reverse proxy in front of the hub. Show the directional flow from external requests to the hub via this web server.
- Infrastructure & Deployment Environments: Additionally, include blocks for Docker containerization, Kubernetes (via Helm charts), and CI/CD pipelines to indicate how the hub moves from development to production.

##### Architectural Patterns & Key Design Principles
- Modular Design: Emphasize how the project is split into clearly defined modules (authentication, event dispatching, transport, configuration) which promotes maintainability and scalability.
- Deployment and Scalability: Highlight the CI/CD workflows, Docker image creation, and Kubernetes deployment resources to show that the project is designed with modern cloud infrastructure in mind.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients Layer
    PublisherClients["Publisher Clients"]:::clients
    SubscriberClients["Subscriber Clients"]:::clients

    %% Integration Layer
    Caddy["Caddy Integration Layer"]:::transport

    %% Core Layer: Mercure Hub Core with submodules
    subgraph "Mercure Hub Core"
        direction TB
        HubMain["Hub Server Core"]:::core
        Auth["JWT Authorization Module"]:::auth
        PubSub["Publisher/Subscriber Interfaces"]:::core
        TransportModule["Transport & Communication Module"]:::transport
        Ancillary["Ancillary Components"]:::ancillary
    end

    %% Deployment & Infrastructure Layer
    Deployment["Deployment & Infra"]:::infra

    %% Data Flow Connections
    PublisherClients -->|"HTTP-request"| Caddy
    Caddy -->|"Routes"| HubMain
    HubMain -->|"Validates/Dispatches"| Auth
    HubMain -->|"Handles PubSub"| PubSub
    HubMain -->|"ManagesTransport"| TransportModule
    HubMain -->|"LogsMetricsVersion"| Ancillary
    HubMain -->|"PushesUpdates"| SubscriberClients
    Deployment ---|"Deploys"| HubMain

    %% Click Events for Component Mapping
    click HubMain "https://github.com/dunglas/mercure/blob/main/cmd/mercure/main.go"
    click HubMain "https://github.com/dunglas/mercure/blob/main/handler.go"
    click HubMain "https://github.com/dunglas/mercure/blob/main/publish.go"
    click HubMain "https://github.com/dunglas/mercure/blob/main/subscribe.go"
    click HubMain "https://github.com/dunglas/mercure/blob/main/event.go"

    click PubSub "https://github.com/dunglas/mercure/blob/main/publish.go"
    click PubSub "https://github.com/dunglas/mercure/blob/main/publish_test.go"
    click PubSub "https://github.com/dunglas/mercure/blob/main/subscribe.go"
    click PubSub "https://github.com/dunglas/mercure/blob/main/subscribe_test.go"
    click PubSub "https://github.com/dunglas/mercure/blob/main/subscriber.go"
    click PubSub "https://github.com/dunglas/mercure/blob/main/subscriber_test.go"

    click Auth "https://github.com/dunglas/mercure/blob/main/authorization.go"
    click Auth "https://github.com/dunglas/mercure/blob/main/authorization_test.go"
    click Auth "https://github.com/dunglas/mercure/blob/main/jwtkeyfunc.go"
    click Auth "https://github.com/dunglas/mercure/blob/main/jwtkeyfunc_test.go"

    click TransportModule "https://github.com/dunglas/mercure/blob/main/transport.go"
    click TransportModule "https://github.com/dunglas/mercure/blob/main/local.go"
    click TransportModule "https://github.com/dunglas/mercure/blob/main/local_test.go"
    click TransportModule "https://github.com/dunglas/mercure/blob/main/local_bench_test.go"
    click TransportModule "https://github.com/dunglas/mercure/blob/main/caddy/mercure.go"
    click TransportModule "https://github.com/dunglas/mercure/blob/main/caddy/local.go"
    click TransportModule "https://github.com/dunglas/mercure/blob/main/caddy/transport.go"

    click Deployment "https://github.com/dunglas/mercure/tree/main/Dockerfile"
    click Deployment "https://github.com/dunglas/mercure/blob/main/Dockerfile.legacy"
    click Deployment "https://github.com/dunglas/mercure/tree/main/charts/mercure"
    click Deployment "https://github.com/dunglas/mercure/tree/main/examples/chat/chart"
    click Deployment "https://github.com/dunglas/mercure/tree/main/.github/workflows"

    click Ancillary "https://github.com/dunglas/mercure/blob/main/metrics.go"
    click Ancillary "https://github.com/dunglas/mercure/blob/main/metrics_test.go"
    click Ancillary "https://github.com/dunglas/mercure/blob/main/log.go"
    click Ancillary "https://github.com/dunglas/mercure/blob/main/log_test.go"
    click Ancillary "https://github.com/dunglas/mercure/blob/main/common/version.go"
    click Ancillary "https://github.com/dunglas/mercure/blob/main/common/version_test.go"

    %% Styles
    classDef clients fill:#AED6F1,stroke:#1B4F72,color:#1B4F72;
    classDef core fill:#A9DFBF,stroke:#196F3D,color:#196F3D;
    classDef transport fill:#F5CBA7,stroke:#943126,color:#641E16;
    classDef auth fill:#D2B4DE,stroke:#6C3483,color:#512E5F;
    classDef infra fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef ancillary fill:#FAD7A0,stroke:#D35400,color:#7D6608;
```
