Skip to content

GuessWho Stereotype Documentation

A lightweight research game for studying stereotype patterns through role-based gameplay.

What this project is

GuessWho Stereotype (Xposed) is a Flask + Socket.IO application with:

  • Moderator-controlled sessions
  • Token-based participant access
  • Two-player role flow (player1 and player2)
  • Live chat and optional voice signaling
  • Full audit-friendly logging into MySQL

Documentation map

  • User Guide: moderator and participant workflows
  • API Reference: endpoints, sockets, and key payloads
  • Roadmap: implementation status and future phases

Architecture snapshot

  • Backend: Flask + Flask-SocketIO
  • Runtime state: Redis (with in-memory fallback)
  • Persistence: MySQL (games, rounds, chat, events, eliminations, tokens)
  • Realtime: Socket.IO and WebRTC signaling

Run with Gunicorn

For a production-style local run, start the app through the Eventlet-enabled WSGI entrypoint:

gunicorn --worker-class eventlet -w 1 --bind 127.0.0.1:5000 --log-level info wsgi:app

Notes:

  • Run this from the project root after installing dependencies from requirements.txt.
  • --worker-class eventlet is required for WebSocket traffic to work correctly with Flask-SocketIO.
  • --bind 127.0.0.1:5000 restricts the server to localhost; use a reverse proxy (Apache/nginx) to expose it externally.
  • Open http://127.0.0.1:5000/ after the server starts.

Notes

  • Token links are one-time use.
  • Session state progression: CLOSED -> OPEN -> READY -> IN_PROGRESS -> ENDED.
  • Moderator is authenticated by session, not a participant identity.