How blitzbugg/ezhuth works
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: Room.jsx Room · handlers.js Handlers · client.js Socket Client · events.js Socket Events
Components 16
Client
React/Vite frontend with local rendering and socket connection
- main · Bootstraps the React app
client/src/main.jsx - App · Top-level app shell and route selection
client/src/App.jsx - Room · Main collaborative drawing screen
client/src/Room.jsx - Draw Store · Local UI and presence state source of truth
client/src/store/useDrawStore.js - Socket Client · Single shared Socket.IO connection
client/src/socket/client.js - Socket Events · Client-side socket event handlers and dispatch
client/src/socket/events.js - Whiteboard · Drawing surface composition and interaction shell
client/src/components/Whiteboard.jsx - Toolbar · Brush, eraser, and tool controls
client/src/components/Toolbar.jsx - Cursor Layer · Renders other users' cursors and presence
client/src/components/CursorLayer.jsx
Server
Node/Express + Socket.IO room relay and lifecycle management
- Server · Express + Socket.IO bootstrap
server/src/server.js - Handlers · Central join, draw, cursor, clear, and disconnect logic
server/src/sockets/handlers.js - Socket Events · Shared socket event constants
server/src/sockets/events.js - Room Manager · Active rooms, stroke logs, and connected users
server/src/rooms/manager.js - Cleanup · Removes empty ephemeral rooms
server/src/rooms/cleanup.js
Connections 20
- 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