How antebrl/undercover-word-game works
Project type and purpose
• This is a single-page, peer-to-peer, full-stack-light application: a React + TypeScript web game (“Undercover word game”) delivered as static assets, where all game logic and state synchronization occur in the browser over WebRTC via PeerJS.
• Purpose: Allow remote players to join a game lobby, assign roles (Civilians, Undercover, Mr. White), exchange secret words, conduct voting rounds and sound effects, and determine victory—all without a dedicated backend service.
File structure
• Top-level build & config:
• vite.config.ts, tsconfig*.json, tailwind.config.ts, postcss.config.js – define build, type, and styling pipelines.
• package.json, bun.lockb – dependency and lockfiles.
• .github/workflows/deploy.yml – CI/CD pipeline to build and deploy.
• Public assets:
• public/sounds – all audio clips used in-game.
• index.html – SPA entry point.
• Source code layout under src/:
• src/main.tsx, src/index.css – entry and global styling.
• src/App.tsx, src/App.css – root component.
• src/components – React components for screens (GameSetup, Lobby, VotingScreen, Results, GameEnd, WordReveal).
• src/components/ui – a complete design-system library (buttons, dialogs, inputs, etc.).
• src/context – global React contexts (GameContext: game state & logic; PeerContext: PeerJS connections; SoundContext: audio control).
• src/hooks – custom hooks (use-mobile detection, use-toast wrapper).
• src/i18n – internationalization setup and locale word pairs.
• src/lib – utility functions.
• src/types – TypeScript types for game entities.
• No dedicated backend/service code—networking handled entirely by PeerJS.
README for additional insights
• Confirms peer-to-peer WebRTC via PeerJS.
• Explains gameplay phases, role distribution, and victory conditions.
• Provides self-host instructions: “npm run dev” with Vite dev server.
a. Main components to represent:
• Client (Browser) – hosts the React SPA.
• UI Layer – React components for game screens & custom UI library.
• State Layer – GameContext (game logic & state machine), SoundContext, PeerContext.
• Hook Layer – custom hooks for device detection and notifications.
• Peer-to-Peer Network – WebRTC connections orchestrated by PeerJS (signaling via PeerJS cloud or self-hosted signaling server).
• Assets & i18n – public/sounds, locale files.
• Build & Deployment – Vite bundler, Tailwind, GitHub Actions → static hosting (e.g., Netlify, GitHub Pages).
b. Relationships & interactions:
• User interacts with UI components → components dispatch actions to GameContext.
• GameContext updates game state and uses PeerContext API to send/receive game events over WebRTC.
• PeerContext mediates signaling with PeerJS server, then establishes direct peer channels.
• SoundContext listens to state changes (e.g., elimination, win/lose) to play appropriate audio.
• Build pipeline (Vite) bundles all source, styles, and assets into static files, deployed via CI/CD.
c. Architectural patterns & design principles:
• Component-based UI (React).
• Context API for global state and cross-cutting concerns (sound, peer connections).
• Separation of concerns: UI vs. logic vs. networking vs. assets.
• Hooks for reusable logic.
• SPA served as static site—no server‐side rendering.
• P2P mesh network for real-time sync without own backend.
d. Key technologies/frameworks:
• React + TypeScript + Vite
• PeerJS (WebRTC signaling & connections)
• Tailwind CSS + shadcn/ui components
• i18next or custom i18n setup
• GitHub Actions for CI/CD