# blitzbugg/ezhuth architecture

> Architecture diagram of the GitHub repository blitzbugg/ezhuth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blitzbugg/ezhuth
- Repository: https://github.com/blitzbugg/ezhuth

## Overview

1. **Repository shape**
   - This is a two-process real-time collaboration app: a React/Vite frontend in `client/` and a Node.js/Express + Socket.IO backend in `server/`.
   - There is no database or account system. Room state lives in server memory, which makes the app fast but ephemeral.

2. **Overall architecture**
   - The server is not a drawing engine; it acts as an event relay and room coordinator.
   - Clients own rendering, canvas state reconstruction, and local interaction. The server mainly forwards drawing and presence events to everyone in the same room.

3. **Frontend runtime and entry points**
   - `client/src/main.jsx` boots the React app and `App.jsx` likely routes between the landing experience and the room view.
   - `Room.jsx` is the main collaborative drawing surface, tying together the canvas, toolbar, cursor overlay, and socket connection.

4. **Canvas rendering boundary**
   - The drawing system is isolated under `client/src/canvas/`.
   - `engine.js` implements the low-level canvas drawing primitives and the two-canvas pattern described in the README: one layer for committed history and one for the active stroke.
   - `replay.js` handles late-join reconstruction by replaying stored strokes and buffering incoming live strokes until replay finishes.

5. **Client state management**
   - `client/src/store/useDrawStore.js` uses Zustand to hold drawing UI state such as brush color, brush size, eraser mode, presence, and possibly room/user identifiers.
   - This store acts as the local source of truth for UI controls, while the canvas itself remains an imperative drawing surface.

6. **Socket client boundary**
   - `client/src/socket/client.js` centralizes the Socket.IO client instance so the app uses a single connection.
   - `client/src/socket/events.js` appears to be the client-side event wiring layer, keeping socket event handling separate from React components and canvas code.

7. **Real-time drawing flow**
   - A user draws in the browser, the stroke is rendered immediately locally for optimistic feedback, and the stroke event is emitted to the server on a throttled cadence.
   - The server appends the stroke to the room’s in-memory log and relays it to other clients in the same room.
   - The originating client ignores its own echoed event, so local rendering stays authoritative and instant.

8. **Room join and late-join replay**
   - Room URLs are the primary collaboration boundary: a UUID-based room ID is encoded in the route and used to scope all socket traffic.
   - When a client joins, the server sends the room’s full `stroke-history`, and the client replays that history into the committed canvas layer.
   - The pending-queue behavior in the README is important architecturally: live strokes that arrive during replay are buffered so the canvas ends up consistent.

9. **Presence and cursor collaboration**
   - Besides drawing, the app broadcasts cursor position and user presence.
   - `CursorLayer.jsx` is likely a pure overlay that renders other users’ pointers, while presence dots and colors are part of the room UI rather than the drawing canvas itself.

10. **Server room management**
   - `server/src/rooms/manager.js` holds the in-memory model for active rooms, stroke logs, and connected users.
   - `cleanup.js` removes empty rooms, which is necessary because there is no persistence layer.
   - This means room lifetime is tied to active sockets, not durable storage.

11. **Socket event boundary**
   - `server/src/sockets/handlers.js` is the central event dispatcher for join, draw, cursor, clear, and disconnect behavior.
   - `server/src/sockets/events.js` likely standardizes event names shared across server logic.
   - The event-driven design keeps collaboration logic flat and explicit: join a room, receive history, then exchange deltas.

12. **Deployment and build concerns**
   - The frontend is built with Vite and includes a `vercel.json`, suggesting the client is intended for static hosting with route handling for room URLs.
   - The backend is a separate Node service on port 3001 in development, with the Vite dev server proxying Socket.IO traffic to it.

13. **Important architectural takeaway**
   - This repo is best understood as a state-sync system, not a CRUD app.
   - The diagram should emphasize: browser-local rendering, Socket.IO event relay, per-room in-memory stroke history, and ephemeral room lifecycle.

Main entry points: [`client/src/Room.jsx`](https://github.com/blitzbugg/ezhuth/blob/master/client/src/Room.jsx) (Room), [`server/src/sockets/handlers.js`](https://github.com/blitzbugg/ezhuth/blob/master/server/src/sockets/handlers.js) (Handlers), [`client/src/socket/client.js`](https://github.com/blitzbugg/ezhuth/blob/master/client/src/socket/client.js) (Socket Client), [`client/src/socket/events.js`](https://github.com/blitzbugg/ezhuth/blob/master/client/src/socket/events.js) (Socket Events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_main(("main<br/>entry<br/>[main.jsx]"))
  node_client_app["App<br/>router<br/>[App.jsx]"]
  node_client_room["Room<br/>collab view<br/>[Room.jsx]"]
  node_client_store[("Draw Store<br/>zustand state<br/>[useDrawStore.js]")]
  node_client_socket_client(("Socket Client<br/>socket.io client<br/>[client.js]"))
  node_client_socket_events["Socket Events<br/>event wiring<br/>[events.js]"]
  node_client_whiteboard["Whiteboard<br/>canvas shell<br/>[Whiteboard.jsx]"]
  node_client_toolbar["Toolbar<br/>controls<br/>[Toolbar.jsx]"]
  node_client_cursor["Cursor Layer<br/>overlay<br/>[CursorLayer.jsx]"]
end

subgraph group_server["Server"]
  node_server_entry(("Server<br/>node service<br/>[server.js]"))
  node_server_handlers["Handlers<br/>socket dispatcher<br/>[handlers.js]"]
  node_server_events["Socket Events<br/>event names<br/>[events.js]"]
  node_server_manager[("Room Manager<br/>in-memory rooms<br/>[manager.js]")]
  node_server_cleanup["Cleanup<br/>room gc<br/>[cleanup.js]"]
end

subgraph group_canvas["Canvas"]
  node_canvas_engine["Engine<br/>[engine.js]"]
  node_canvas_replay["Replay<br/>history sync<br/>[replay.js]"]
end

node_client_main -->|"boot"| node_client_app
node_client_app -->|"route"| node_client_room
node_client_room -->|"reads state"| node_client_store
node_client_room -->|"connects"| node_client_socket_client
node_client_room -->|"renders"| node_client_whiteboard
node_client_room -->|"controls"| node_client_toolbar
node_client_room -->|"overlay"| node_client_cursor
node_client_room -->|"draws"| node_canvas_engine
node_client_room -->|"replays"| node_canvas_replay
node_client_socket_client -->|"wires"| node_client_socket_events
node_canvas_replay -->|"uses"| node_canvas_engine
node_client_socket_client -.->|"socket io"| node_server_entry
node_server_entry -->|"dispatches"| node_server_handlers
node_server_handlers -->|"uses"| node_server_events
node_server_handlers -->|"updates"| node_server_manager
node_server_handlers -->|"triggers"| node_server_cleanup
node_server_manager -->|"prunes"| node_server_cleanup
node_server_handlers -.->|"broadcasts"| node_client_socket_client
node_client_socket_events -->|"syncs"| node_client_store
node_client_room -->|"subscribes"| node_client_socket_events

click node_client_main "https://github.com/blitzbugg/ezhuth/blob/master/client/src/main.jsx"
click node_client_app "https://github.com/blitzbugg/ezhuth/blob/master/client/src/App.jsx"
click node_client_room "https://github.com/blitzbugg/ezhuth/blob/master/client/src/Room.jsx"
click node_client_store "https://github.com/blitzbugg/ezhuth/blob/master/client/src/store/useDrawStore.js"
click node_client_socket_client "https://github.com/blitzbugg/ezhuth/blob/master/client/src/socket/client.js"
click node_client_socket_events "https://github.com/blitzbugg/ezhuth/blob/master/client/src/socket/events.js"
click node_client_whiteboard "https://github.com/blitzbugg/ezhuth/blob/master/client/src/components/Whiteboard.jsx"
click node_client_toolbar "https://github.com/blitzbugg/ezhuth/blob/master/client/src/components/Toolbar.jsx"
click node_client_cursor "https://github.com/blitzbugg/ezhuth/blob/master/client/src/components/CursorLayer.jsx"
click node_canvas_engine "https://github.com/blitzbugg/ezhuth/blob/master/client/src/canvas/engine.js"
click node_canvas_replay "https://github.com/blitzbugg/ezhuth/blob/master/client/src/canvas/replay.js"
click node_server_entry "https://github.com/blitzbugg/ezhuth/blob/master/server/src/server.js"
click node_server_handlers "https://github.com/blitzbugg/ezhuth/blob/master/server/src/sockets/handlers.js"
click node_server_events "https://github.com/blitzbugg/ezhuth/blob/master/server/src/sockets/events.js"
click node_server_manager "https://github.com/blitzbugg/ezhuth/blob/master/server/src/rooms/manager.js"
click node_server_cleanup "https://github.com/blitzbugg/ezhuth/blob/master/server/src/rooms/cleanup.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_main,node_client_app,node_client_room,node_client_store,node_client_socket_client,node_client_socket_events,node_client_whiteboard,node_client_toolbar,node_client_cursor toneBlue
class node_server_entry,node_server_handlers,node_server_events,node_server_manager,node_server_cleanup toneAmber
class node_canvas_engine,node_canvas_replay toneMint
```

## Components

### Client

React/Vite frontend with local rendering and socket connection

- [main](https://github.com/blitzbugg/ezhuth/blob/master/client/src/main.jsx): entry · Bootstraps the React app · `client/src/main.jsx`
- [App](https://github.com/blitzbugg/ezhuth/blob/master/client/src/App.jsx): router · Top-level app shell and route selection · `client/src/App.jsx`
- [Room](https://github.com/blitzbugg/ezhuth/blob/master/client/src/Room.jsx): collab view · Main collaborative drawing screen · `client/src/Room.jsx`
- [Draw Store](https://github.com/blitzbugg/ezhuth/blob/master/client/src/store/useDrawStore.js): zustand state · Local UI and presence state source of truth · `client/src/store/useDrawStore.js`
- [Socket Client](https://github.com/blitzbugg/ezhuth/blob/master/client/src/socket/client.js): socket.io client · Single shared Socket.IO connection · `client/src/socket/client.js`
- [Socket Events](https://github.com/blitzbugg/ezhuth/blob/master/client/src/socket/events.js): event wiring · Client-side socket event handlers and dispatch · `client/src/socket/events.js`
- [Whiteboard](https://github.com/blitzbugg/ezhuth/blob/master/client/src/components/Whiteboard.jsx): canvas shell · Drawing surface composition and interaction shell · `client/src/components/Whiteboard.jsx`
- [Toolbar](https://github.com/blitzbugg/ezhuth/blob/master/client/src/components/Toolbar.jsx): controls · Brush, eraser, and tool controls · `client/src/components/Toolbar.jsx`
- [Cursor Layer](https://github.com/blitzbugg/ezhuth/blob/master/client/src/components/CursorLayer.jsx): overlay · Renders other users' cursors and presence · `client/src/components/CursorLayer.jsx`

### Server

Node/Express + Socket.IO room relay and lifecycle management

- [Server](https://github.com/blitzbugg/ezhuth/blob/master/server/src/server.js): node service · Express + Socket.IO bootstrap · `server/src/server.js`
- [Handlers](https://github.com/blitzbugg/ezhuth/blob/master/server/src/sockets/handlers.js): socket dispatcher · Central join, draw, cursor, clear, and disconnect logic · `server/src/sockets/handlers.js`
- [Socket Events](https://github.com/blitzbugg/ezhuth/blob/master/server/src/sockets/events.js): event names · Shared socket event constants · `server/src/sockets/events.js`
- [Room Manager](https://github.com/blitzbugg/ezhuth/blob/master/server/src/rooms/manager.js): in-memory rooms · Active rooms, stroke logs, and connected users · `server/src/rooms/manager.js`
- [Cleanup](https://github.com/blitzbugg/ezhuth/blob/master/server/src/rooms/cleanup.js): room gc · Removes empty ephemeral rooms · `server/src/rooms/cleanup.js`

### Canvas

Imperative drawing and replay boundary

- [Engine](https://github.com/blitzbugg/ezhuth/blob/master/client/src/canvas/engine.js): render engine · Low-level canvas drawing primitives and committed/live layers · `client/src/canvas/engine.js`
- [Replay](https://github.com/blitzbugg/ezhuth/blob/master/client/src/canvas/replay.js): history sync · Late-join stroke replay and live-stroke buffering · `client/src/canvas/replay.js`

## Connections

- main → App: boot · Starts the React application
- App → Room: route · Renders the collaboration room view
- Room → Draw Store: reads state · Consumes drawing, presence, and room state
- Room → Socket Client: connects · Uses the shared Socket.IO connection
- Room → Whiteboard: renders · Composes the drawing surface
- Room → Toolbar: controls · Exposes drawing tools
- Room → Cursor Layer: overlay · Shows collaborator pointers and presence
- Room → Engine: draws · Delegates imperative canvas rendering
- Room → Replay: replays · Reconstructs history for late joiners
- Socket Client → Socket Events: wires · Binds socket events to app logic
- Replay → Engine: uses · Replays strokes into the committed canvas layer
- Socket Client → Server: socket io · Transports collaboration events to the backend
- Server → Handlers: dispatches · Routes socket activity into collaboration handlers
- Handlers → Socket Events: uses · Shares event names across server logic
- Handlers → Room Manager: updates · Adds strokes, rooms, and user presence in memory
- Handlers → Cleanup: triggers · Cleans up empty rooms after disconnects
- Room Manager → Cleanup: prunes · Room lifecycle depends on active sockets
- Handlers → Socket Client: broadcasts · Relays draw and presence events to room peers
- Socket Events → Draw Store: syncs · Updates local UI and presence state from socket traffic
- Room → Socket Events: subscribes · Consumes room join, history, draw, and cursor events
