Skip to content

Home

Jump to bottom
Neptunov edited this page Mar 8, 2026 · 10 revisions

Welcome to the Classic Mafia Draft App

Welcome to the official documentation for the Classic Mafia Draft App - Tournament Edition.

This application is a professional-grade, local-network draft management system built specifically for live Classic Mafia tournaments. It replaces physical cards with a secure, digital ecosystem that prevents cheating, provides instant moderator tracking, and generates cinematic 3D overlays for live OBS broadcasts.

🗺️ System Architecture

Understanding how the application communicates is key to setting up your tournament. The system uses a centralized Client-Server architecture powered by WebSockets.

🧠 The Core: Node.js Backend

At the center of the application is a lightweight Node.js server. It acts as the "Dealer" and the absolute source of truth for the tournament:

  • Real-Time Sync: Uses Socket.io to instantly push updates (like card picks or timer starts) to all connected devices.
  • Security: The underlying 10-card deck is never sent over the network to players. The server strictly sanitizes state payloads, sending only what a specific device is authorized to see.
  • Persistence: Every action, device session, and table state is instantly saved to an encrypted store.json file on the host machine. If the power goes out, the server reboots exactly where it left off.

📱 The Clients: React Frontend

Connected to the core are the individual web interfaces. Any tablet, smartphone, or PC on the same Wi-Fi network can access these views:

  • 🛡️ Admin Console: The command center. Used by tournament organizers to create tables, toggle Single Mode, spawn Phantom players for testing, and route specific tables to OBS sources.
  • ⚖️ Judge View: The moderator's dashboard. A color-coded, 1-10 list that tracks the draft live. Judges can force picks, remotely close cards on player screens, and reset the draft.
  • 🃏 Player View: The interactive velvet tray. This is where players tap physical card backs to reveal their roles. The 3D reveal is strictly synchronized with the Stream Overlay.
  • 🎥 Stream Overlay: A transparent cinematic view designed to be added as a Browser Source in OBS. It features an "Audience Protection Timer" to guarantee viewers can read the role even if the player taps away instantly.

📚 Table of Contents

Ready to get started? Navigate through the Wiki to configure your tournament:

  1. Installation & Setup: Learn how to build the app, find your local IP address, and initialize your master password.
  2. The Admin Console: A guide to creating tables, reading the Overview Plates, and using Global Debug mode safely.
  3. Tournament Modes Explained: Detailed breakdowns of Shared Tablet Mode vs. Single Device Mode (and how to properly seat players).
  4. Stream Overlays (OBS): Step-by-step instructions for adding the stream to OBS, verifying it in the Admin panel, and aligning the 3D cards.
  5. The Moderator (Judge) View: A cheat sheet for live moderation, tracking colors, and handling player disconnects.
  6. The Storage Vault (v0.3.0 Architecture): New local data protection system documentation.
  7. i18n & RTL Architecture (v0.3.1+): Dynamic Context Provider to manage languages.
  8. Asset Pack Manager & Cropping Studio: Custom Asset Engine to manage card and tray textures and a GUI to import, export or create your own asset packs.

🤖 Development Transparency Notice: The core architecture, application logic, and tournament rules for this project were designed and directed by the human developer. Artificial Intelligence (specifically Google's Gemini) was utilized as an advanced pair-programming assistant to generate boilerplate syntax, optimize CSS layouts, debug React race conditions, and draft this Wiki documentation.

Clone this wiki locally