Collaborative Whiteboard

A real-time collaborative whiteboard application built with FastAPI, Vue.js, and Valkey. Draw, collaborate, and share ideas in real-time with multiple users.

Features

• Real-time collaborative drawing
• Multiple users can draw simultaneously
• WebSocket-based synchronization
• Persistent storage with Valkey
• Responsive web interface

Prerequisites

Choose one of the following methods to run the application:

Option 1: Docker (Recommended)

• Docker (v20.10+)
• Docker Compose (v2.0+)

Option 2: Local Development with uv

• Python (3.11+)
• uv - Fast Python package installer
• Valkey

Installation & Setup

Option 1: Running with Docker (Recommended)

This is the easiest way to get started. Docker will handle all dependencies and setup automatically.

1. Clone the repository

   git clone <repository-url>
   cd demo

2. Start the application

   docker-compose up -d

   Or use the shortcut:

   make run

   This will start:

   • Valkey server on port 6379
   • Whiteboard backend on port 8000

3. Access the application

   Open your browser and navigate to:

   http://localhost:8000
   

4. View logs (optional)

   docker-compose logs -f whiteboard-backend

5. Stop the application

   docker-compose down

   To remove volumes as well:

   docker-compose down -v

Option 2: Running Locally with uv

For local development without Docker, use uv for faster dependency installation.

1. Clone the repository

   git clone <repository-url>
   cd demo

2. Install uv (if not already installed)

   # On macOS and Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # On Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Install Valkey

   On macOS:

   brew install valkey
   brew services start valkey

   On Ubuntu/Debian:

   sudo apt-get install valkey-server
   sudo systemctl start valkey-server

   On Windows:

   • Use Valkey Docker image [https://valkey.io/download/]

4. Create a virtual environment and install dependencies

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -r requirements.txt

5. Configure environment variables (optional)

   Copy .env.example to .env in the root directory:

   cp .env.example .env

   Then adjust values if needed:

   VALKEY_HOST=localhost
   VALKEY_PORT=6379
   VALKEY_DB=0
   MAX_STROKES_PER_ROOM=10000
   ADMIN_INSIGHTS_TOKEN=change-me

6. Run the application

   cd backend
   uvicorn main:app --host 0.0.0.0 --port 8000 --reload

7. Access the application

   Open your browser and navigate to:

   http://localhost:8000
   

Development

Project Structure

demo/
├── backend/
│   ├── __init__.py
│   ├── main.py          # FastAPI application entry point
│   ├── api.py           # API routes and WebSocket handlers
│   ├── database.py      # Valkey connection and operations
│   ├── models.py        # Data models
│   └── connections.py   # WebSocket connection management
├── frontend/
│   ├── index.html       # Main HTML file
│   └── assets/          # Static assets (CSS, JS)
├── docker-compose.yml   # Docker Compose configuration
├── Dockerfile          # Docker image configuration
├── requirements.txt    # Python dependencies
└── README.md          # This file

Making Changes

When running with Docker, the application automatically reloads when you make changes to the code (hot reload enabled).

For local development with uv, the --reload flag enables hot reloading.

API Endpoints

HTTP Endpoints

• GET / - Serve the frontend application
• GET /health - Basic healthcheck endpoint
• GET /assets/* - Serve static assets
• POST /api/feedback - Capture product feedback from users
• POST /api/telemetry - Capture product funnel events
• GET /api/admin/insights - Token-protected 24h aggregate of telemetry + feedback

WebSocket Endpoints

• WS /ws/{room_id} - Real-time collaboration WebSocket connection for a room

Protocol and Replay Behavior

• WebSocket messages use protocol_version=1
• New clients bootstrap with recent history (up to 1500 strokes) for faster loads
• stroke_count returns total room strokes, while history may be truncated for performance
• Stroke streams are capped using MAX_STROKES_PER_ROOM to keep memory bounded

Admin Insights

• Set ADMIN_INSIGHTS_TOKEN in .env
• Send it as header x-admin-token when calling GET /api/admin/insights
• Response includes last 24h event counts, feedback rating mix, negative feedback rate, active unique rooms, and recent feedback samples
• Optional UI dashboard: open http://localhost:8000/admin/insights, enter the token, and load metrics

Room Sharing

• Open a specific room by URL query param: http://localhost:8000/?room=my-team-room
• Use the Copy Share Link button in the toolbar to invite collaborators to the same room
• Room IDs support letters, numbers, _, and - (max 64 chars)

User Feedback Collection

• A feedback widget is shown in the app so users can send thumbs up/down and optional notes
• Feedback is stored in Valkey stream key whiteboard:feedback

Technologies Used

• Backend: FastAPI, Python 3.11
• Database: Valkey
• Frontend: Vue.js, HTML5 Canvas
• Real-time: WebSocket (Socket.IO)
• Containerization: Docker, Docker Compose

Smoke Test

Run a quick backend/API contract check:

export ADMIN_INSIGHTS_TOKEN=change-me
python scripts/smoke_test.py

Optional base URL override:

SMOKE_BASE_URL=http://localhost:8000 python scripts/smoke_test.py

Shortcut:

ADMIN_INSIGHTS_TOKEN=change-me make smoke

Benchmark shortcut:

make benchmark
CLIENTS=50 DURATION=30 make benchmark

Troubleshooting

Docker Issues

Port already in use:

# Check what's using the port
netstat -ano | findstr :8000  # Windows
lsof -i :8000                 # macOS/Linux

# Change the port in docker-compose.yml
ports:
  - "8001:8000"  # Use 8001 instead

Container won't start:

# Check logs
docker-compose logs whiteboard-backend

# Rebuild containers
docker-compose up --build

Local Development Issues

Module not found:

# Reinstall dependencies
uv pip install -r requirements.txt

Port 8000 already in use:

# Run on a different port
uvicorn main:app --host 0.0.0.0 --port 8001

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is open source and available under the MIT License.

Support

For issues, questions, or contributions, please open an issue on the repository.

Talk Idea

Talk planning content lives in docs/talk-idea.md.