How d-led/ssr-robust-live-svg works
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.”