Identity-Verified Multiplayer Arena

CS6.201 — Introduction to Software Systems, S26

A full-stack real-time multiplayer web application with biometric login. Players authenticate via facial recognition against scraped profile images, then enter a live lobby to challenge each other to Tic-Tac-Toe. Ratings update after every match using the Elo system.

Stack

Layer	Technology
Backend	FastAPI (Python)
Real-time	WebSockets
Relational DB	MySQL 8 (Docker)
Asset DB	MongoDB Atlas
Facial Recognition	face-recognition (dlib)
Containerisation	Docker + Docker Compose

Project Structure

.
├── main.py                            # FastAPI app, all routes and WebSocket endpoints
├── db.py                              # MySQL + MongoDB connection helpers
├── scraper.py                         # One-time data harvesting script (Phase 1)
├── lobby_classes.py                   # WebSocket connection manager, Elo logic
├── mysql_schema.sql                   # MySQL schema (auto-run by Docker on first start)
├── batch_data.csv                     # Student uid, name, website_url data
├── docker-compose.yml
├── Dockerfile
├── utils/
│   ├── auth.py                        # Facial auth pipeline, session management
│   ├── facial_recognition_module.py   # Black-box module (do not modify)
│   └── face_recog_tester.py
├── login.html / login.css / login.js
├── lobby.html / lobby.css / lobby.js
├── leaderboard.html / leaderboard.css / leaderboard.js
└── styles.css                         # Shared styles

Database Schemas

MySQL — relational_data database

CREATE TABLE IF NOT EXISTS users (
    uid        VARCHAR(50)  PRIMARY KEY,
    name       VARCHAR(100) NOT NULL,
    elo_rating INT          DEFAULT 1200,
    is_online  BOOLEAN      DEFAULT FALSE
);

This table is automatically created by Docker on first startup via mysql_schema.sql. You do not need to run this manually.

MongoDB Atlas — ImgAssetStorage_DB database

Collection: results

{
  "uid":         "2025XXXXXX",
  "image_bytes": "<binary image data>"
}

No schema setup needed — MongoDB is schemaless. The scraper populates this collection.

Prerequisites

• Docker + Docker Compose installed and running
• A .env file in the project root (get this from a teammate — never committed to git)
• MongoDB Atlas cluster with network access set to 0.0.0.0/0 (allow from anywhere)

.env format

connection_string=mongodb://username:password@cluster.mongodb.net/?authSource=admin
mysql_host=mysql
mysql_user=root
mysql_password=rootpassword
mysql_database=relational_data

Use mongodb:// not mongodb+srv:// — the SRV format causes connection issues in Docker.

Setup and Running

Step 1 — Build and start containers

docker compose up --build   # first time (takes 10–20 min due to dlib compilation)
docker compose up           # subsequent starts

Step 2 — Run the scraper (once only)

In a separate terminal while containers are running:

docker compose exec app python3 scraper.py

This scrapes profile images from each student's website, stores them in MongoDB, and inserts user metadata into MySQL. Only needs to be run once — data persists across restarts.

Step 3 — Access the app

# Find your local IP
ip addr show | grep "inet " | grep -v 127.0.0.1   # Linux
ipconfig getifaddr en0                              # Mac

• You (host): http://localhost:8000
• Other players (same WiFi): http://<your-local-ip>:8000
• Remote access via ngrok: ./ngrok http 8000 then share the https:// URL

Note: First startup takes a few extra minutes — the server pre-computes face encodings for all students before accepting requests. Watch progress with docker compose logs app --follow and wait for CACHE BUILT before trying to log in.

Note: If hosting via ngrok, camera access works out of the box since ngrok provides HTTPS. For local network HTTP on Chrome, go to chrome://flags/#unsafely-treat-insecure-origin-as-secure, add your IP URL, set to Enabled, and relaunch. Firefox allows camera on local HTTP by default.

Common Commands

Command	What it does
docker compose up --build	First-time build and start
docker compose up	Start normally
docker compose down	Stop everything
docker compose logs app --follow	Watch app logs live
docker compose exec app python3 scraper.py	Run scraper (once only)
docker compose exec mysql mysql -u root -prootpassword relational_data -e "SELECT uid, name, is_online, elo_rating FROM users;"	Inspect MySQL data

Common Pitfalls

• Face not recognised at login: Check if the database has records. If empty, run docker compose exec app python3 scraper.py to populate it.
• MongoDB timeout on startup: Your network may be blocking port 27017. Switch to mobile hotspot and try again. University/corporate WiFi often blocks this port.
• Camera not working on Chrome over HTTP: Use the Chrome flag workaround above, or use ngrok for HTTPS.
• Port 8000 not reachable from other devices: Run sudo firewall-cmd --add-port=8000/tcp --permanent && sudo firewall-cmd --reload on Linux.

Assumptions Made

• All profile images are accessible at <website_url>/images/pfp.jpg
• One person hosts the server; all players connect via browser
• MongoDB Atlas network access is set to allow connections from anywhere (0.0.0.0/0)
• The mongodb:// connection string format must be used instead of mongodb+srv:// due to Docker networking constraints
• The facial recognition threshold is 0.7 as set in facial_recognition_module.py
• Face encodings are pre-computed once at server startup via build_encodings_cache() — login is fast after startup, but first startup takes time proportional to the number of students in the database
• Player Elo ratings start at 1200 (standard chess default)
• A player who disconnects mid-game forfeits the match

Dependencies

Python packages (installed via Docker):

fastapi, uvicorn, pymongo, mysql-connector-python,
python-dotenv, face-recognition, numpy, pillow,
requests, jinja2, websockets

AI Usage

This project used generative AI tools (Claude and Gemini) for boilerplate generation, HTML/CSS styling, syntax debugging, and Docker configuration assistance. All system architecture, design decisions, and integration logic were independently developed by the team. Full chat logs with prompts and model outputs are attached as required per the AI usage policy.

Anya

• Code: https://claude.ai/share/59fb1331-2ea5-4e2e-9c65-3e784b08f482
• Hosting/debugging: https://claude.ai/share/3f7b5f35-9694-4284-a84f-7212330c3950
• Useless Debugging: https://chatgpt.com/share/69e68b99-4458-83e8-9dc3-6494a3a3ad47

Arnav (Gemini Student Pro)

• Fixing Python Build Errors on Mac
• NumPy Tic-Tac-Toe Game Implementation
• dlib Build Failure on macOS
• MongoDB Upsert Function Correction
• Building a Tic-Tac-Toe Lobby
• What error is this? Traceback passed
• FastAPI WebSocket Game Connection Management
• Comparing Python Authentication Code
• Code Review: Facial Recognition Login
• Camera Access: Secure Context Required
• Fix Hatchling Package Not Found Error
• Docker Compose Cache and Rebuild
• Uvicorn MongoDB Operation Cancelled Error
• Docker Compose Startup Successful
• WebSocket Disconnect Error Loop
• Update Lobby JS for Player List
• Docker Build Timeout Error Resolution

Shevani

Initilly taken screenschots are on the google doc and some links are at the bottom of the doc

• https://docs.google.com/document/d/1lZZ7Fe1MExfZODeU-9toUBUXoG5SkhAcMdTlqjWs_AI/edit?usp=sharing Leaderboard

• https://chatgpt.com/share/69e66e07-5ff4-8322-8d4e-a89c163acb96 Mysql database

• https://chatgpt.com/share/69e66ea8-21c0-8320-a300-66b57fbf039e

• https://chatgpt.com/share/69e66ec1-cb7c-83a3-a2d1-04d0f9345214

Mysql related

• https://chatgpt.com/share/69e66ed8-5cb0-8320-a055-b03b37a0fc79

Mongobd altas setup

• https://chatgpt.com/share/69e66f07-fc68-8321-ad86-a01d8af38f0b

debugging

• https://chatgpt.com/share/69e66f1c-ba34-8321-b3c1-01daa727b255

Leaderboard

• https://chatgpt.com/share/69e66e07-5ff4-8322-8d4e-a89c163acb96

Ngrok setup and more debugging

• https://chatgpt.com/share/69e66f34-7ecc-8324-8e79-a88fbc320f59