# antebrl/undercover-word-game architecture

> Architecture diagram of the GitHub repository antebrl/undercover-word-game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antebrl/undercover-word-game
- Repository: https://github.com/antebrl/undercover-word-game

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "UI Layer" 
        direction TB
        GameSetup["GameSetup Component"]:::ui
        GameLobby["Lobby Component"]:::ui
        MultiplayerSetup["MultiplayerSetup Component"]:::ui
        VotingScreen["Voting Screen"]:::ui
        ResultsScreen["Results Screen"]:::ui
        GameEnd["Game End Screen"]:::ui
        WordReveal["Word Reveal Screen"]:::ui
        subgraph "Shared UI Elements"
            direction TB
            MrWhiteGuess["MrWhiteGuess"]:::ui
            PlayerList["PlayerList"]:::ui
        end
    end

    %% Design System
    DesignSystem["UI Library\n(src/components/ui)"]:::ui

    %% State & Logic Layer
    subgraph "State Layer"
        direction TB
        GameContext["GameContext\n(State & Logic)"]:::state
        PeerContext["PeerContext\n(PeerJS Network)"]:::state
        SoundContext["SoundContext\n(Audio)"]:::state
    end

    %% Hook Layer
    subgraph "Hooks Layer"
        direction TB
        UseMobile["use-mobile Hook"]:::state
        UseToast["use-toast Hook"]:::state
    end

    %% i18n & Assets
    subgraph "Assets & i18n"
        direction TB
        I18n["i18n Setup & Locales"]:::asset
        Sounds["Public Sounds"]:::asset
    end

    %% Network
    PeerJS["PeerJS Signaling\n(Cloud or Self-Hosted)"]:::network
    subgraph "P2P Mesh"
        direction TB
        PeerMesh["WebRTC Peer Connections"]:::network
    end

    %% Build & Deployment
    subgraph "Build & Deploy"
        direction TB
        Vite["Vite Build\n(vite.config.ts)"]:::build
        Tailwind["Tailwind & PostCSS"]:::build
        CI["GitHub Actions\n(deploy.yml)"]:::build
        Hosting["Static Hosting\n(Netlify/GH Pages)"]:::build
    end

    %% Entry Points
    Main["Main Entry\n(src/main.tsx)"]:::state
    App["App Component\n(src/App.tsx)"]:::state
    IndexCSS["Global CSS\n(src/index.css)"]:::state

    %% Relationships
    GameSetup -->|renders| GameContext
    GameLobby -->|renders| GameContext
    MultiplayerSetup -->|dispatches| GameContext
    VotingScreen -->|dispatches| GameContext
    ResultsScreen -->|dispatches| GameContext
    GameEnd -->|dispatches| GameContext
    WordReveal -->|dispatches| GameContext

    GameSetup -->|uses| DesignSystem
    GameLobby -->|uses| DesignSystem
    MultiplayerSetup -->|uses| DesignSystem
    VotingScreen -->|uses| DesignSystem
    ResultsScreen -->|uses| DesignSystem
    GameEnd -->|uses| DesignSystem
    WordReveal -->|uses| DesignSystem
    MrWhiteGuess -->|uses| DesignSystem
    PlayerList -->|uses| DesignSystem

    DesignSystem -->|imported by| App

    GameContext -->|sends/receives| PeerContext
    PeerContext -->|signals via| PeerJS
    PeerJS -->|establishes| PeerMesh
    PeerMesh -->|triggers| GameContext

    GameContext -->|updates| SoundContext
    SoundContext -->|plays| Sounds

    GameContext -->|reads| I18n

    Main -->|boots| App
    App -->|injects| GameContext
    App -->|injects| PeerContext
    App -->|injects| SoundContext
    App -->|imports| IndexCSS

    %% Build flow
    Main -->|bundled by| Vite
    App -->|bundled by| Vite
    IndexCSS -->|processed by| Tailwind
    Vite -->|deploys via| CI
    CI -->|publishes to| Hosting
    Sounds -->|included in| Vite
    I18n -->|included in| Vite

    %% Click Events
    click GameSetup "https://github.com/antebrl/undercover-word-game/blob/main/src/components/GameSetup.tsx"
    click GameLobby "https://github.com/antebrl/undercover-word-game/blob/main/src/components/GameLobby.tsx"
    click MultiplayerSetup "https://github.com/antebrl/undercover-word-game/blob/main/src/components/MultiplayerSetup.tsx"
    click VotingScreen "https://github.com/antebrl/undercover-word-game/blob/main/src/components/VotingScreen.tsx"
    click ResultsScreen "https://github.com/antebrl/undercover-word-game/blob/main/src/components/Results.tsx"
    click GameEnd "https://github.com/antebrl/undercover-word-game/blob/main/src/components/GameEnd.tsx"
    click WordReveal "https://github.com/antebrl/undercover-word-game/blob/main/src/components/WordReveal.tsx"
    click MrWhiteGuess "https://github.com/antebrl/undercover-word-game/blob/main/src/components/shared/MrWhiteGuess.tsx"
    click PlayerList "https://github.com/antebrl/undercover-word-game/blob/main/src/components/shared/PlayerList.tsx"
    click DesignSystem "https://github.com/antebrl/undercover-word-game/tree/main/src/components/ui/"
    click GameContext "https://github.com/antebrl/undercover-word-game/blob/main/src/context/GameContext.tsx"
    click PeerContext "https://github.com/antebrl/undercover-word-game/blob/main/src/context/PeerContext.tsx"
    click SoundContext "https://github.com/antebrl/undercover-word-game/blob/main/src/context/SoundContext.tsx"
    click UseMobile "https://github.com/antebrl/undercover-word-game/blob/main/src/hooks/use-mobile.tsx"
    click UseToast "https://github.com/antebrl/undercover-word-game/blob/main/src/hooks/use-toast.ts"
    click I18n "https://github.com/antebrl/undercover-word-game/blob/main/src/i18n/index.ts"
    click Sounds "https://github.com/antebrl/undercover-word-game/tree/main/public/sounds/"
    click Main "https://github.com/antebrl/undercover-word-game/blob/main/src/main.tsx"
    click App "https://github.com/antebrl/undercover-word-game/blob/main/src/App.tsx"
    click IndexCSS "https://github.com/antebrl/undercover-word-game/blob/main/src/index.css"
    click Vite "https://github.com/antebrl/undercover-word-game/blob/main/vite.config.ts"
    click Tailwind "https://github.com/antebrl/undercover-word-game/blob/main/tailwind.config.ts"
    click CI "https://github.com/antebrl/undercover-word-game/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#075985,stroke-width:1px
    classDef state fill:#D1FAE5,stroke:#047857,stroke-width:1px
    classDef network fill:#FFEDD5,stroke:#C2410C,stroke-width:1px
    classDef asset fill:#FEF3C7,stroke:#92400E,stroke-width:1px
    classDef build fill:#E5E7EB,stroke:#374151,stroke-width:1px
```
