BoredRoom is a browser-based Nigerian party-game platform. A desktop or TV hosts one house session, players join once from their phones, and every installed game runs through the same server-authoritative connection.
Current platform version: 1.15.0.1
Current signed games release: 1.10.0.0
Create session → players join → choose game → configure → play → recap → choose next game
- Desktop and TV devices host the public display.
- Phones act as private controllers.
- Tablets can act as controllers or optional host companions.
- Late players wait or join the crowd until a seat is available.
- Controllers switch games without changing route, connection, or room code.
Games are installed from the signed BoredRoom-Games catalog. A fresh deployment can contain no games; owners install only what they need.
The official catalog currently contains 15 games, including Ludo, Whot, Oga Landlord, Money Trivia, Faith Feud, Connect 4, Word Wahala, and Color Wahala.
Each active run is pinned to an exact artifact version. The server verifies the catalog source, archive path, SHA-256 digest, Ed25519 signature, manifest, and runtime contract before activation.
| Layer | Implementation |
|---|---|
| Web/PWA | React, TypeScript, Vite, Tailwind CSS |
| Realtime | Colyseus and Express |
| Contracts | Shared TypeScript and Zod schemas |
| Persistence | Optional server-side Supabase access |
| Games | Signed ESM runtime plugins on persistent storage |
| AI | Optional server-side DeepSeek structured output |
| Speech | Optional server-side YarnGPT synthesis |
| Deployment | Docker Compose |
HouseSessionRoom is the only realtime room. It owns membership, seating, lifecycle transitions, snapshots, role-safe projections, votes, recaps, and recovery. Browsers never receive owner credentials, model credentials, signing material, another player's private state, or hidden answer banks.
Requirements: Node.js 22+, npm, and Docker when testing the production stack.
git clone https://github.com/thathman/BoredRoom.git
cd BoredRoom
npm install
npm --prefix server install
cp .env.example .envStart the frontend and server in separate terminals:
npm run dev
npm --prefix server run devLocal defaults are http://localhost:8080 for the web app and ws://localhost:2567 for Colyseus.
Deployment addresses and credentials belong in environment configuration, not source code.
| Variable | Scope | Purpose |
|---|---|---|
VITE_COLYSEUS_URL |
Build-time frontend | Public WebSocket URL for the realtime server. |
WEB_ORIGINS |
Server | Comma-separated browser origins allowed by CORS. |
GAME_ADMIN_TOKEN |
Server | Owner passphrase for game administration. |
GAME_ADMIN_ORIGINS |
Server | Optional stricter origins for owner mutations. |
SUPABASE_URL |
Server | Optional persistence endpoint. |
SUPABASE_SERVICE_ROLE_KEY |
Server | Optional server-only persistence credential. |
DEEPSEEK_API_KEY |
Server | Optional AI provider credential. |
DEEPSEEK_MODEL |
Server | AI model identifier. |
DEEPSEEK_BASE_URL |
Server | AI API endpoint. |
TTS_API_KEY |
Server | Optional speech-synthesis credential. |
TTS_BASE_URL |
Server | Speech-synthesis endpoint. |
TTS_VOICES |
Server | Allowed voice rotation. |
BOREDROOM_GAMES_DIR |
Server | Persistent installed-game directory. |
BOREDROOM_GAMES_CATALOG_URL |
Server | Signed catalog URL. |
BOREDROOM_GAMES_PUBLIC_KEY |
Server | Artifact verification key. |
Only VITE_ variables are compiled into browser assets. Never place service-role, owner, AI, TTS, or signing credentials in frontend variables.
npm run gates:releaseThe release gate runs lint, TypeScript checks, unit/integration tests, the production PWA build, server build, and dependency audits. Relevant browser flows are available as smoke:* scripts in package.json, including entry, host controls, voting, gameplay, reconnect, and Money Trivia.
Set all required values in .env, then build the generic Compose stack:
docker compose up -d --buildFor SSH deployment, use the host-neutral script with explicit targets:
TARGET_HOST=<ssh-host> TARGET_DIR=<remote-directory> bash scripts/deploy-remote.shNo production hostname, IP address, or remote filesystem path is compiled into the application.