PixelBattle

Backend for a real-time collaborative pixel canvas built for a live event. Participants connect over WebSocket, receive the shared field and publish individual pixel updates. The service validates each action, persists the canonical pixel state in PostgreSQL and broadcasts accepted deltas to connected participants and administrators.

This repository is a cleaned public snapshot of the event backend.

Event result

• Load-tested with 1.5K-2K concurrent WebSocket connections.
• Broadcast update latency remained below 50 ms during the event test.
• Flutter client integration through an explicit WebSocket protocol.
• Prometheus instrumentation for active connections and message traffic.

The load-test figures are event evidence, not values emitted by the included Prometheus counters.

Accepted pixel flow

WebSocket update
  -> schema and bounds validation
  -> per-user cooldown check
  -> PostgreSQL timestamp-guarded upsert
  -> in-process broadcast to active clients

PostgreSQL owns users, pixels and the last accepted update time. The ConnectionManager owns active sockets, nicknames and transient selections in process memory.

Stack

• FastAPI and Starlette WebSocket
• PostgreSQL with psycopg async pool
• Pydantic schemas
• Prometheus and Grafana
• Docker Compose

Local development

1. Copy .env.example to .env.
2. Replace every replace_with_... value.
3. Build and start the local stack:

docker compose build
docker compose up

Default local endpoints:

• HTTP documentation: http://localhost:8000/docs
• WebSocket: ws://localhost:8000/ws/
• Prometheus metrics in debug mode: http://localhost:8000/metrics

docker-compose.yaml is a development configuration and starts Uvicorn with reload enabled.

Protocol and architecture

• Project brief
• Architecture
• HTTP contract
• WebSocket contract
• WebSocket message reference

The first WebSocket message authenticates a participant by nickname/user ID or an administrator by JWT. User actions include field state, selection, online count and pixel updates. Administrative actions include cooldown changes, moderation and event reset.

Security boundary

• Secrets and database passwords are required through environment variables.
• Production mode restricts CORS to FRONTEND_URL.
• Destructive database initialization and application metrics exposure are enabled only in debug mode.
• Administrator passwords are verified against bcrypt hashes stored in the database; the development fallback account is disabled outside debug mode.

Rotate any credential that has previously been committed or deployed.

Tests

The current WebSocket tests are integration tests and require a running backend and PostgreSQL instance:

pytest

Scaling boundary

Broadcast and transient selections are intentionally in-process. Horizontal scaling would require an external fan-out layer and shared coordination for ephemeral state.