Technical Case Study: Mafia Game Manager - Engineering Real-Time Social Deduction

Introduction

Mafia Game Manager started as a hobby project to solve a specific problem: the logistical nightmare of running a 15-player Mafia game. As the solo developer, I wanted to create a "digital game engine" that could handle role tracking, secret actions, and phase transitions, allowing the Game Master and players to focus on the game's social aspects.

The Problem: The Logistical Burden of Social Deduction

In a typical game of Mafia, the Game Master (GM) must:

Track Secret Identities: Ensure nobody forgets their role.
Resolve Complex Actions: Determine what happens when Mafia kills a player while a Doctor saves them.
Manage Information Flow: Prevent "information leaks" where players accidentally see data they shouldn't.
Maintain Pacing: Keep the game moving with timers and clear phase transitions.

Solution Architecture: Real-Time Sync & Selective State

I architected a system that prioritizes real-time performance and strict data isolation.

The Stack:

Backend: NestJS with a modular architecture for rooms, auth, and game logic.
Real-Time: Socket.io for instant synchronization and event-driven updates.
State Management: Redis for active game state to ensure low-latency interactions.
Database: MongoDB for persistent player profile and game history data.
Frontend: Next.js (CSR) with Framer Motion for immersive UI transitions.

Overcoming Key Challenges

Challenge 1: The "Morning Resolver" Priority Queue

Resolving player actions during the Night phase can be complex. If the Mafia kills Player A, but the Doctor heals Player A, and the Bodyguard protects Player B... who dies?

Problem: Nested if-else blocks for conflict resolution are brittle and hard to test.
Solution: I implemented a deterministic "Morning Resolver". This service collects all cached actions from Redis at the end of the Night phase and processes them using a priority-based algorithm. Protective roles (Doctor, Bodyguard) are calculated first, followed by offensive roles (Mafia, Vigilante), ensuring a consistent and bug-free outcome every game.

Challenge 2: Zero-Leak Data Isolation

In a social deduction game, information is everything. The server must never send Player B's role to Player A's browser.

Problem: Standard WebSocket "broadcast" sends the same payload to everyone in a room.
Solution: I built a selective payload generator in the Socket Gateway. When the game state updates, the backend generates unique snapshots for each player based on their role and status (Alive/Ghost). Only the Game Master receives the "Full God View," while players only see what their role allows, effectively preventing client-side data mining.

Challenge 3: Maintaining Immersion via "Second Screen" UX

The app is intended to be used on smartphones during in-person play, requiring a mobile-first, immersive design.

Problem: Standard web forms feel "clinical" and can break the game's atmosphere.
Solution: I leveraged Framer Motion to create thematic "Phase Transitions." When the game moves from Day to Night, the UI undergoes a shift (Sun to Moon animation), accompanied by heartbeat pulses for high-stakes actions like targeting. The "Tap to Flip" card reveal was engineered for tactile satisfaction, mimicking the feel of physical role cards.

Results & Impact

Seamless Gameplay: Successfully reduced "Phase Transition" time by 80% by automating the resolution logic.
Accuracy: Eliminated GM errors in role tracking and action resolution.
Scalability: The Redis-backed architecture handles 20+ concurrent players in a single room with zero noticeable lag.

Conclusion

The Mafia Game Manager demonstrates that even "hobby" projects can benefit from high-end engineering. By applying professional standards—strict TypeScript, Redis-driven state, and event-driven architecture—I turned a complex manual process into a polished digital experience.

Launch Mafia Game Manager