# emre-emiroglu/hmsignalbus architecture

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

- Interactive diagram: https://gitdiagram.com/emre-emiroglu/hmsignalbus
- Repository: https://github.com/emre-emiroglu/hmsignalbus

## Overview

##### Project type and purpose
- This is a Unity runtime package (installed via UPM) that implements an in-engine, event-driven “signal bus” following the publish-subscribe pattern. Its sole purpose is to provide loose-coupled messaging between components in a Unity project.

##### File structure
- Top-level files: LICENSE.md, README.md, package.json ⇒ metadata for a Unity Package
- Runtime/… : contains three C# scripts and their Unity asmdef ⇒ core implementation that ships in the package
- SignalBus.cs: the core bus managing declarations, subscriptions, and firing
- SignalBinding.cs: per-signal registry handling subscriber lists, priority ordering, and invocation
- SignalBusUtilities.cs: static façade & bootstrapper (uses Unity’s RuntimeInitializeOnLoad to create the singleton bus before any scene loads)

##### README for insights
- Confirms pub-sub features: Declare, Subscribe (with priority), Unsubscribe, Fire
- Explains exceptions and warnings for misuse
- Highlights the use of Unity attributes to guarantee bus initialization

##### Main components and their interactions
a. Unity Runtime Initialization
- Unity’s engine loads code marked with [RuntimeInitializeOnLoadMethod] in SignalBusUtilities ⇒ creates a singleton SignalBus instance before scene load
b. SignalBusUtilities (static façade)
- Exposes Declare<T>, Subscribe<T>, Unsubscribe<T>, Fire<T> methods
- Delegates all calls to the underlying SignalBus instance
c. SignalBus
- Manages a dictionary of SignalBinding<T> by signal type T
- On Declare<T>: creates a new SignalBinding<T> entry (or throws if already declared)
- On Subscribe/Unsubscribe/Fire<T>: finds the SignalBinding<T> and calls its Add/Remove/Invoke
d. SignalBinding<T>
- Holds an ordered list of subscriber callbacks plus priority
- Implements Add (with priority), Remove, Invoke (in priority order), HasReceivers
e. Client Components (any MonoBehaviour / C# class in the user’s game code)
- Call SignalBusUtilities.Declare<MySignal>() at startup
- Subscribe/unsubscribe methods using SignalBusUtilities
- Fire new signal instances via SignalBusUtilities.Fire(new MySignal())

##### Architectural patterns & principles
- Pub-sub / observer pattern for loose coupling
- Singleton service (SignalBus) managed by a static façade (SignalBusUtilities)
- Generic registry per signal type for type safety and zero-reflection at runtime
- Early initialization via Unity lifecycle hooks to avoid manual bootstrap

##### Final checklist
- Clear component labels: class names and roles
- Optional inset showing the Tests folder’s EditMode and PlayMode tests invoking the public API for validation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Unity Engine Lifecycle
    UnityEngine["Unity Engine\n[RuntimeInitializeBeforeSceneLoad]"]:::engine

    %% SignalBus Subsystem
    subgraph "SignalBus Subsystem"
        SBUtils["SignalBusUtilities\n(static façade & bootstrap)"]:::facade
        SB["SignalBus\n(singleton core)"]:::core
        SBinding["SignalBinding<T>\n(generic registry)"]:::binding
        asmdef["CodeCatGames.HMSignalBus.Runtime.asmdef"]:::metadata
    end

    %% Client Components
    subgraph "Client Components"
        Client["MonoBehaviour/C# Classes\n(Call Declare/Subscribe/Fire)"]:::client
    end

    %% Tests
    subgraph "Tests" 
        direction TB
        EditMode["EditMode Tests"]:::test
        PlayMode["PlayMode Tests"]:::test
    end

    %% Metadata & Docs
    subgraph "Package Metadata & Docs"
        pkgjson["package.json"]:::metadata
        readme["README.md"]:::metadata
        license["LICENSE.md"]:::metadata
    end

    %% Relationships
    UnityEngine -->|"Initialize() BeforeSceneLoad"| SBUtils
    SBUtils -->|"constructs"| SB
    SBUtils -->|"Declare<T>() / Subscribe<T>() / Fire<T>()"| SB
    SB -->|"holds dictionary of"| SBinding
    SBinding -->|"Invoke() in priority order"| Client
    Client -->|"calls Declare/Subscribe/Fire"| SBUtils
    EditMode -->|"tests API"| SBUtils
    PlayMode -->|"tests API"| SBUtils

    %% Click Events
    click SBUtils "https://github.com/emre-emiroglu/hmsignalbus/blob/main/Runtime/SignalBusUtilities.cs"
    click SB "https://github.com/emre-emiroglu/hmsignalbus/blob/main/Runtime/SignalBus.cs"
    click SBinding "https://github.com/emre-emiroglu/hmsignalbus/blob/main/Runtime/SignalBinding.cs"
    click asmdef "https://github.com/emre-emiroglu/hmsignalbus/blob/main/Runtime/CodeCatGames.HMSignalBus.Runtime.asmdef"
    click EditMode "https://github.com/emre-emiroglu/hmsignalbus/blob/main/Tests/EditMode/SignalBusEditModeTests.cs"
    click PlayMode "https://github.com/emre-emiroglu/hmsignalbus/blob/main/Tests/PlayMode/SignalBusPlayModeTests.cs"
    click pkgjson "https://github.com/emre-emiroglu/hmsignalbus/blob/main/package.json"
    click readme "https://github.com/emre-emiroglu/hmsignalbus/blob/main/README.md"
    click license "https://github.com/emre-emiroglu/hmsignalbus/blob/main/LICENSE.md"

    %% Styles
    classDef engine fill:#FFA500,stroke:#333,stroke-width:1px
    classDef facade fill:#00FF00,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef binding fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef client fill:#FFFF00,stroke:#333,stroke-width:1px
    classDef test fill:#DDDDDD,stroke-dasharray: 5 5,stroke:#999,stroke-width:1px
    classDef metadata fill:#EEEEEE,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2

    %% Legend
    subgraph "Legend"
        direction TB
        L1["Orange = Unity Engine"]:::engine
        L2["Green = Static Façade"]:::facade
        L3["Blue = Core Library"]:::core
        L4["Light Blue = Generic Binding"]:::binding
        L5["Yellow = Client Code"]:::client
        L6["Gray Dashed = Tests"]:::test
        L7["Light Gray Dashed = Metadata & Docs"]:::metadata
    end
```
