Sketchline Backend — Real-time WebSocket Server

FastAPI + WebSocket backend powering Sketchline — a real-time collaborative whiteboard. Handles room management, stroke history, live cursor sync, and connection keepalive.

Frontend Repo · Live Demo

---

✨ Features

• Room-based WebSocket sessions — each board is an isolated room via /ws/{room_id}
• Stroke history replay — new users receive full stroke history on join; room persists 60s after last user leaves
• Live cursor sync — broadcasts cursor positions with display names and assigned colors
• Auto display names — assigns animal-style names (e.g. "Swift Otter") and unique colors if none provided
• Ping / pong keepalive — heartbeat every 20s with 15s pong timeout to detect dead connections
• Undo / Redo sync — undo and redo events broadcast to all users in the room
• CORS locked — only the Vercel frontend and localhost are permitted

---

🛠 Tech Stack

Layer	Technology
Framework	FastAPI
WebSocket	websockets 14.1
Server	Uvicorn (standard)
Language	Python 3.11
Container	Docker
Deployment	Render

---

📁 Project Structure

whiteboard-backend/
├── main.py            # All routes, WebSocket handler, room logic
├── requirements.txt   # fastapi, uvicorn[standard], websockets
├── Dockerfile         # Production container
└── railway.json       # ⚠️ Leftover file — safe to delete

---

🔌 API Reference

Method	Endpoint	Description
GET	/	Health check — returns {"status": "ok"}
GET	/rooms/{room_id}/stats	Room info — user count, stroke count
WS	/ws/{room_id}?name=YourName	WebSocket connection for a board room

WebSocket messages — server → client

Type	Description
init	Full stroke history + current users sent on join
user_joined	Another user entered the room
user_left	A user disconnected
stroke_start / stroke_point / stroke_end	Live stroke broadcast
cursor	Remote cursor position + name
undo / redo / clear	Board state events
ping	Keepalive ping (client must reply pong)

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• Or Docker

Run locally (without Docker)

git clone https://github.com/sugumaran-nix/whiteboard-backend.git
cd whiteboard-backend
pip install -r requirements.txt
uvicorn main:app --host 127.0.0.1 --port 8080 --reload

Health check: curl http://localhost:8080/ → {"status":"ok"}

Run with Docker

docker build -t whiteboard-backend .
docker run -p 8080:8080 whiteboard-backend

---

🌐 Deployment (Render)

1. Push to GitHub
2. Go to render.com → New Web Service → connect your repo
3. Render auto-detects the Dockerfile and builds
4. Once deployed, copy your service URL (e.g. https://your-backend.onrender.com)
5. Set the frontend env var: NEXT_PUBLIC_WS_URL=wss://your-backend.onrender.com

---

⚙️ Environment

No environment variables required for the backend itself. CORS origins are hardcoded — update the allow_origins list in main.py if you deploy the frontend to a custom domain.

---

📄 License

MIT