Club Impostor

Overview

Club Impostor is a sophisticated browser-based multiplayer social deduction game similar to Mafia or Werewolf, where players assume roles as either civilians or impostors. The core gameplay loop involves discussion phases, voting rounds, and argument-based elimination, requiring real-time synchronization across multiple clients while maintaining game state consistency on the server. The architecture supports two distinct modes—single-device local play with no server interaction and multi-device networked play with full server orchestration—allowing flexible deployment and ensuring the game works seamlessly whether players are on one device or distributed across the internet.

Technical architecture

The technical foundation leverages a modern monorepo architecture with a React 19 + TypeScript + Vite frontend and an Express + TypeScript backend, both deployed on Vercel infrastructure. The client utilizes advanced state management through Zustand for local state and TanStack Query for server data synchronization, while the server implements a robust Socket.io layer for real-time game events. Game state is persisted in a Turso/LibSQL database (SQLite-compatible, edge-hosted) with Drizzle ORM for type-safe queries. Critical infrastructure components include Redis for distributed rate limiting (protecting both HTTP endpoints and WebSocket connections), JWT-based session management with refresh token rotation, and integration with Better Auth for enterprise-grade authentication flows including Google OAuth.

Real-time multiplayer & voice communication

Voice communication is implemented through mediasoup, a cutting-edge WebRTC framework that enables peer-to-peer audio without relying on third-party VoIP services. The server manages SFU (Selective Forwarding Unit) functionality, allowing multiple players to speak simultaneously with low latency, while the client handles microphone acquisition, audio encoding/decoding, and real-time stream management. This architecture eliminates VoIP licensing costs while providing OPUS-encoded audio streams with adaptive bitrate control. The implementation includes sophisticated error recovery for microphone permission issues, permission state monitoring, and graceful fallback when audio hardware is unavailable.

Content & economic systems

The game’s content system - word categories, word generation, and game parameters - is dynamically powered by the Vercel AI Gateway, which provides on-demand word generation for custom categories without relying on static word lists. A multi-layer caching strategy with Redis backend and in-memory application caches ensures sub-100ms word retrieval for common categories, critical for maintaining snappy lobby load times even under high player count. The server implements rate limiting per user and per IP address for word generation requests, protecting against abuse while maintaining smooth gameplay initialization.

Economic and progression systems add depth through multiple interconnected layers: an achievement system with tracked progress and rarity tiers, a ranking system with ELO-style calculations that persist across seasons, and an in-game currency economy with two tiers (earned currency from gameplay, purchasable premium currency for cosmetics). The Bazaar module manages cosmetic inventory, player skins, in-game titles, and seasonal battle passes. Purchase events trigger webhook validations for security, preventing fraudulent transactions while maintaining transactional integrity through Drizzle’s type-safe mutations.

Performance & infrastructure

The architecture addresses complex challenges in real-time multiplayer gaming: game state reconciliation when players reconnect mid-game (rehydrating timers, current turn state, and role information without desynchronizing other players), optimal WebSocket message batching to reduce bandwidth while maintaining perceived responsiveness, and efficient room management with automatic cleanup of stale sessions. Recent development focused on enhancing microphone robustness (detecting permission changes and session permission states), implementing word selection feedback mechanisms with request deduplication, and optimizing Google login flows to handle session state transitions seamlessly. Performance optimizations include aggressive code splitting via Vite with per-route chunks, prefetching critical game flow pages on lobby entry, and virtual scrolling for leaderboards supporting thousands of concurrent rankings. The admin dashboard provides real-time monitoring of active games, player statistics, content management, and support tools for user account management—essential infrastructure for maintaining a production multiplayer service.