# lucerion/pub_sub_hub architecture

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

## Overview

- Hub – The core service that manages users, channels, subscriptions, tokens, and internal RPC handling. It also handles the persistence of data (e.g., via Ecto migrations in the priv/repo directory).
- Publisher – A client application that authenticates with the Hub, creates channels, and publishes content.
- Subscriber – Another client application that authenticates, subscribes to channels, and receives published data.

##### Main Components
a. Hub Service:
– Acts as the central coordinator.
– Contains multiple submodules (users, channels, subscriptions, tokens, RPC handling).
– Manages database interactions (see the migrations and repo files).
b. Publisher Service:
– Authenticates against the Hub.
– Invokes RPC methods to create channels and publish data.
c. Subscriber Service:
– Authenticates against the Hub.
– Uses RPC calls to subscribe/unsubscribe and to receive messages.
d. Database:
– Used by the Hub for storing user credentials, channel definitions, subscriptions, and more.
e. RPC Mechanism:
– Facilitates inter-process communication between the Hub, Publisher, and Subscriber.
– Clearly visible in the structure by having dedicated modules (e.g., PubSubHub.Publisher.RPC.Supervisor, PubSubHub.Subscriber.RPC.Supervisor) and corresponding lib files.

##### Relationships and Interactions
– From Publisher → Hub highlighting authentication, channel creation, and publishing data.
– From Subscriber → Hub showing authentication and subscription management.

##### Architectural Patterns and Design Principles
a. Modular and decoupled design: Each major app (hub, publisher, subscriber) is an independent OTP application, ensuring clear separation of concerns.
b. Use of RPC: The system leverages Elixir’s capabilities for remote procedure calls between distributed nodes, ensuring loose coupling.
c. Persistence Layer: Use of Ecto migrations and a dedicated repository indicates a clear data persistence pattern.
d. Supervisory Structure: Indicated by the presence of Application modules and supervisor directories, it emphasizes fault tolerance and robust process management.

##### Relevant Technologies and Frameworks
a. Elixir (and OTP) is the core language and framework behind the system.
b. Ecto for database interactions.
c. The RPC-based mechanism inspired by WebSub for pub/sub communications.
d. To note the use of environment variables (via .env files) for configuration.

##### Overall Advice
– Be as detailed as possible. Break down the Hub into its internal components (Users, Channels, Subscriptions, Tokens, RPC Handlers) if needed; this helps in visualizing the internal responsibilities.
– Focus on data flow: from client actions (create publisher/subscriber, authentication, channel management) toward the Hub and then to the persistence layer or back to the clients.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    P("Publisher"):::publisher
    S("Subscriber"):::subscriber

    %% Hub Service Subgraph
    subgraph "Hub Service"
        %% User Management
        U1("Users (Main)"):::hub
        U2("User Detail"):::hub

        %% Channel Management
        C1("Channels (Main)"):::hub
        C2("Channel Detail"):::hub

        %% Subscription Management
        SM1("Subscriptions (Main)"):::hub
        SM2("Subscription Detail"):::hub

        %% Token Management
        T("Token"):::hub
        Sec("Secret"):::hub

        %% RPC Handling
        RPChub("RPC Hub"):::rpc
        RPCpub("RPC Publisher"):::rpc
        RPCsub("RPC Subscriber"):::rpc
    end

    %% Database Subgraph
    subgraph "Database"
        Repo("Repo"):::database
        Migrations("Migrations"):::database
        Seeds("Seeds"):::database
    end

    %% Interactions
    P -->|"Auth/Create/Publish"| RPCpub
    S -->|"Auth/Subscribe/Unsubscribe"| RPCsub
    RPCpub -->|"RPC_call"| RPChub
    RPCsub -->|"RPC_call"| RPChub
    RPCpub -->|"ChannelCreation"| C1
    RPCsub -->|"SubscriptionMgmt"| SM1
    RPChub -->|"Persistence"| Repo

    %% Database internal connections
    Repo -->|"Has"| Migrations
    Repo -->|"Has"| Seeds

    %% Styles
    classDef publisher fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef subscriber fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef hub fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef rpc fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef database fill:#ffe6cc,stroke:#333,stroke-width:2px;

    %% Click Events for Hub Service modules
    click U1 "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/hub/users.ex"
    click U2 "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/hub/users/user.ex"
    click C1 "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/hub/channels.ex"
    click C2 "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/hub/channels/channel.ex"
    click SM1 "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/hub/subscriptions.ex"
    click SM2 "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/hub/subscriptions/subscription.ex"
    click T "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/hub/token.ex"
    click Sec "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/hub/secret.ex"
    click RPChub "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/rpc/hub.ex"
    click RPCpub "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/rpc/publisher.ex"
    click RPCsub "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/rpc/subscriber.ex"

    %% Click Events for Publisher and Subscriber
    click P "https://github.com/lucerion/pub_sub_hub/blob/master/apps/publisher/lib/publisher.ex"
    click S "https://github.com/lucerion/pub_sub_hub/blob/master/apps/subscriber/lib/subscriber.ex"

    %% Click Events for Database components
    click Repo "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/lib/repo.ex"
    click Migrations "https://github.com/lucerion/pub_sub_hub/tree/master/apps/hub/priv/repo/migrations"
    click Seeds "https://github.com/lucerion/pub_sub_hub/blob/master/apps/hub/priv/repo/seeds.exs"
```
