# d-led/ssr-robust-live-svg architecture

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

- Interactive diagram: https://gitdiagram.com/d-led/ssr-robust-live-svg
- Repository: https://github.com/d-led/ssr-robust-live-svg

## Overview

##### Project’s nature and goal
- This is a clustered Elixir/Phoenix LiveView application that animates a virtual ball inside a browser using server-side SVG updates.
- It practices OTP concurrency by externalizing state, simulating node failures, and maintaining a single “Ball” process across nodes.

##### Key conceptual processes and actors
- Browser Client: renders the SVG and sends user interactions (e.g. “change behavior” commands) over WebSocket.
- Phoenix Endpoint & LiveView (WorldLive): receives events from the Ball and ClusterInfoServer via PubSub, pushes minimal DOM diffs to the client, and forwards UI commands back to OTP processes.
- Ball (singleton): an OTP GenServer running on exactly one cluster node; computes the ball’s next position according to a pluggable “BallMovement” protocol implementation.
- Behavior Modules (e.g. MirrorJump, RandomRebound): implement the BallMovement protocol; Ball invokes them to decide its next state.
- StateGuardian: local to each node, stores the last known ball state so that when Ball restarts (or moves nodes) it can reload its position without loss.
- ClusterInfoServer: polls the Erlang cluster, maintains the list of live nodes, and broadcasts it to LiveView to display cluster topology.
- NodeKillSwitch: exposes a control to deliberately crash the local node; on exit, the cluster re-elects a new Ball process on another node.
- PubSub Bus: the communication backbone for broadcasting “ball moved” events, node-list updates, and UI command trips.

##### Relationships and message flows
- Client → LiveView: UI commands (e.g. “switch behavior,” “trigger fault”) via WebSocket bindings.
- LiveView → PubSub → OTP processes: forwards commands to Ball or NodeKillSwitch.
- Ball ↔ Behavior Modules: Ball calls the selected behavior protocol to compute the next (x,y) and direction.
- Ball → StateGuardian: after each move, Ball persists its new state. On restart, Ball queries StateGuardian.
- Ball → PubSub → LiveView: Ball broadcasts its updated transform (SVG coordinates).
- ClusterInfoServer → PubSub → LiveView: periodically broadcasts current node list.
- NodeKillSwitch → OS: causes node crash; cluster rebalances and starts a new Ball on another node.

##### Architectural patterns and principles
- Singleton: one Ball process in the entire cluster at any time.
- Protocol-driven behavior injection: behaviors implement a BallMovement protocol.
- Externalized state: StateGuardian isolates persistence from Ball’s lifecycle, enabling seamless restarts.
- Fault tolerance: NodeKillSwitch simulates crashes; cluster re-election of Ball ensures continuity.
- PubSub-based decoupling: LiveView doesn’t call Ball directly but subscribes to events, reducing tight coupling.

##### Detail without over-engineering
- Singleton nature of Ball by marking it “1 of N nodes.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Client
    BrowserClient["Browser Client"]:::ui
    click BrowserClient "https://github.com/d-led/ssr-robust-live-svg/blob/main/assets/js/app.js"
    click BrowserClient "https://github.com/d-led/ssr-robust-live-svg/blob/main/assets/css/app.css"

    %% PubSub Bus
    PubSubBus["PubSub Bus"]:::infra

    %% Behavior Modules
    subgraph "Behavior Modules" 
        direction TB
        MirrorJump["MirrorJump"]:::behavior
        RandomRebound["RandomRebound"]:::behavior
    end
    click MirrorJump "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live/actor_behaviors/mirror_jump.ex"
    click RandomRebound "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live/actor_behaviors/random_rebound.ex"

    %% BallMovement Protocol
    BallProtocol["BallMovement Protocol"]:::behavior
    click BallProtocol "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live/protocols/ball_movement.ex"

    %% Nodes
    subgraph "Node A"
        direction TB
        AppSupA["Application Supervisor"]:::infra
        click AppSupA "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live/application.ex"
        Ball["Ball (1 of N)"]:::state
        click Ball "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live/actors/ball.ex"
        StateGuardA["StateGuardian"]:::state
        click StateGuardA "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live/state_guardian.ex"
        ClusterInfoA["ClusterInfoServer"]:::infra
        click ClusterInfoA "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live/cluster_info_server.ex"
        KillSwitchA["NodeKillSwitch"]:::infra
        click KillSwitchA "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live/node_kill_switch.ex"
        VersionA["VersionServer"]:::infra
        click VersionA "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live/version_server.ex"
        EndpointA["Phoenix Endpoint"]:::live
        click EndpointA "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live_web/endpoint.ex"
        WorldLiveA["WorldLive"]:::live
        click WorldLiveA "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live_web/live/world_live.ex"
        RouterA["Router"]:::live
        click RouterA "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live_web/router.ex"
        SVGComp["CircleComponent"]:::live
        click SVGComp "https://github.com/d-led/ssr-robust-live-svg/blob/main/lib/braitenberg_vehicles_live_web/components/circle_component.ex"

        AppSupA --> StateGuardA
        AppSupA --> ClusterInfoA
        AppSupA --> KillSwitchA
        AppSupA --> VersionA
        AppSupA --> PubSubBus
        EndpointA --> WorldLiveA
        WorldLiveA --> PubSubBus
    end

    subgraph "Node B"
        direction TB
        AppSupB["Application Supervisor"]:::infra
        AppSupB --> StateGuardB["StateGuardian"]:::state
        AppSupB --> ClusterInfoB["ClusterInfoServer"]:::infra
        AppSupB --> KillSwitchB["NodeKillSwitch"]:::infra
        AppSupB --> VersionB["VersionServer"]:::infra
        AppSupB --> PubSubBus
        EndpointB["Phoenix Endpoint"]:::live
        WorldLiveB["WorldLive"]:::live
        EndpointB --> WorldLiveB
        WorldLiveB --> PubSubBus
    end

    subgraph "Node C"
        direction TB
        AppSupC["Application Supervisor"]:::infra
        AppSupC --> StateGuardC["StateGuardian"]:::state
        AppSupC --> ClusterInfoC["ClusterInfoServer"]:::infra
        AppSupC --> KillSwitchC["NodeKillSwitch"]:::infra
        AppSupC --> VersionC["VersionServer"]:::infra
        AppSupC --> PubSubBus
        EndpointC["Phoenix Endpoint"]:::live
        WorldLiveC["WorldLive"]:::live
        EndpointC --> WorldLiveC
        WorldLiveC --> PubSubBus
    end

    %% Browser to LiveView
    BrowserClient -->|"ui_command"| WorldLiveA
    BrowserClient -->|"ui_command"| WorldLiveB
    BrowserClient -->|"ui_command"| WorldLiveC

    %% Ball to Behavior & State & PubSub
    Ball -->|"invoke compute"| BallProtocol
    BallProtocol -->|"return next state"| Ball
    Ball -->|"persist_state"| StateGuardA
    Ball -->|"move_event"| PubSubBus

    %% ClusterInfoServer to PubSub
    ClusterInfoA -->|"cluster_update"| PubSubBus
    ClusterInfoB -->|"cluster_update"| PubSubBus
    ClusterInfoC -->|"cluster_update"| PubSubBus

    %% PubSub to LiveView
    PubSubBus -->|"move_event"| WorldLiveA
    PubSubBus -->|"cluster_update"| WorldLiveA
    PubSubBus -->|"move_event"| WorldLiveB
    PubSubBus -->|"cluster_update"| WorldLiveB
    PubSubBus -->|"move_event"| WorldLiveC
    PubSubBus -->|"cluster_update"| WorldLiveC

    classDef state fill:#cfc,stroke:#393,stroke-width:2px
    classDef infra fill:#ccf,stroke:#339,stroke-width:2px
    classDef live fill:#fc9,stroke:#c60,stroke-width:2px
    classDef ui fill:#f96,stroke:#d60,stroke-width:2px
    classDef behavior fill:#eee,stroke:#999,stroke-width:1px
```
