🎭 MemeGame

MemeGame is an online multiplayer party game designed for community-ranked meme battles. Players join a shared room, spin a roulette wheel to select a prompt creator, craft custom sentences, and submit matching meme GIFs fetched in real time from Giphy.

Rather than relying on a single subjective judge to pick winners, MemeGame features community ranked voting (🥇 1st place • 🥈 2nd place • 🥉 3rd place). Every player votes blindly on anonymized submissions, and round winners are determined algorithmically by point totals.

The platform is designed around two core tenets:

• Low onboarding friction: Players can jump into a room immediately as a guest using a 6-character room code without creating an account or verifying an email address.
• Authoritative synchronization: The server acts as the single source of truth for timers, game phase transitions, score validation, and reconnection state.

MemeGame operates as an authoritative state machine where phase transitions are driven and validated by the backend server.

stateDiagram-v2
    [*] --> RoomLobby: Join via 6-Char Code
    RoomLobby --> promptSpinner: Host Starts Game
    
    state "1. Prompt Spinner" as promptSpinner
    state "2. Sentence Creation" as sentenceCreation
    state "3. Meme Selection" as memeSelection
    state "4. Community Voting" as voting
    state "5. Meme Reveal" as memeReveal
    state "6. Scoring Round" as scoring
    state "7. Round Results" as results
    state "8. Final Results" as finalResults
    
    promptSpinner --> sentenceCreation: Creator Selected
    sentenceCreation --> memeSelection: Prompt Submitted / Timeout
    memeSelection --> voting: Memes Submitted (90s Timer)
    voting --> memeReveal: All Players Vote
    memeReveal --> scoring: Author Reveal Complete
    scoring --> results: Points Awarded
    results --> promptSpinner: Next Round (Current < Total)
    results --> finalResults: Game Over (Current == Total)
    finalResults --> RoomLobby: Host Selects Play Again
    finalResults --> [*]: Leave Room

1. Room Lobby: Players join via a 6-character room code. The host selects round counts (3–8 rounds) and initiates the match.
2. Prompt Spinner: An animated wheel selects the Prompt Creator for the round.
3. Sentence Creation: The Prompt Creator inputs a custom sentence or chooses from curated prompt decks.
4. Meme Selection: Players select their funniest GIF from their 7-card hand before the round timer expires.
5. Community Voting: Anonymized submissions are displayed. Players cast 1st, 2nd, and 3rd place votes.
6. Meme Reveal & Scoring: Authors are unmasked, and round-wise winners and score deltas are calculated.
7. Round Results: Displays the round winner card alongside updated tournament standings.
8. Final Results: Crowds the overall match champion and generates a shareable PNG summary card.

MemeGame uses a decoupled client-server architecture with real-time bi-directional WebSocket communication.

graph TD
    subgraph Client [React 18 / Vite Frontend]
        UI[Neo-Brutalist Components]
        CTX[Game & Auth State Contexts]
        WS_CLIENT[Socket.IO Client]
    end

    subgraph CDN [External Infrastructure]
        GIPHY[GIPHY API • GIF Stream]
        AVATARS[DiceBear Avatar Service]
    end

    subgraph Server [Python 3 / Flask Backend]
        REST_API[REST API Routes]
        WS_SERVER[Socket.IO Event Dispatcher]
        SECURITY[JWT & OTP Authentication]
        ROOM_STATE[Authoritative Room State Machine]
    end

    subgraph Persistence [Storage & Caching]
        MONGO[(MongoDB Atlas • 7 Collections)]
        REDIS[(Redis Cache & Rate Limiter)]
        FALLBACK[In-Memory Store Fallback]
    end

    UI <-->|React Hooks| CTX
    CTX <-->|WebSocket Events| WS_CLIENT
    WS_CLIENT <-->|WSS / JSON Payloads| WS_SERVER
    UI <-->|HTTPS REST| REST_API
    
    WS_SERVER --> SECURITY
    REST_API --> SECURITY
    SECURITY --> ROOM_STATE
    ROOM_STATE <-->|Query & Mutate| MONGO
    ROOM_STATE <-->|Rate Limit & Cache| REDIS
    REDIS -.->|Graceful Fallback| FALLBACK
    
    ROOM_STATE -->|Fetch GIF Decks| GIPHY
    UI -->|Render SVG Avatars| AVATARS

• Frontend Client: Built with React 18, TypeScript, Tailwind CSS, and Framer Motion. Uses socket.io-client to synchronize UI state with the backend and automatically negotiate connection recovery.
• Authoritative Server: Python 3 backend using Flask and Flask-SocketIO. Owns room timers, phase transitions, and score calculations to prevent client-side manipulation.
• Database & Caching Layer: Uses MongoDB Atlas for durable storage (user accounts, rooms, sessions, OTP verification records, feedback, contact inquiries, and historical game results) and Redis for IP rate limiting and transient session caching, with automatic fallback to local memory when Redis is offline.

MemeGame uses a Neo-Brutalist visual identity characterized by bold typography, high-contrast borders, warm pastel backgrounds, and structured Bento grid layouts.

┌──────────────────────────────────────────────────────────┐
│  #FFDDAB (Warm Cream Page Canvas)                        │
│  ┌────────────────────────────────────────────────────┐  │
│  │  2px Solid #131010 Border                          │  │
│  │  ┌──────────────────────────────────────────────┐  │  │
│  │  │  Bento Card Content                          │  │  │
│  │  └──────────────────────────────────────────────┘  │  │
│  │  Hard Offset Shadow (4px x 4px #131010)            │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

• Color Tokens:
  • Warm Cream (#FFDDAB): Primary background canvas that reduces glare while preserving contrast.
  • Carbon Black (#131010): High-contrast color for typography, border outlines, and drop shadows.
  • Amber Orange (#D98324): Primary accent used for primary call-to-action buttons and winner tags.
  • Forest Green (#5F8B4C): Positive success state used for badges and winning scores.
• Tactile Interactions: Buttons depress physically on click, and dialogs animate smoothly using Framer Motion spring transitions.
• Accessibility & Mobile Responsiveness: Exceeds WCAG AAA contrast guidelines, enforces minimum 44px touch targets, supports keyboard navigation, and automatically adapts layouts across mobile and desktop viewports.

To keep this introductory README readable, comprehensive engineering and API documentation is organized into modular reference guides:

• docs/ARCHITECTURE.md — Detailed breakdown of the authoritative state machine, room synchronization, and Socket.IO event payloads.
• docs/DATABASE.md — Document schemas, indexing strategies, and relationships across all 7 MongoDB collections.
• docs/API.md — Complete REST API endpoint specifications, authentication headers, and request/response JSON schemas.
• docs/DEPLOYMENT.md — Production hosting instructions for deploying the Flask backend and React frontend.
• docs/CONTRIBUTING.md — Guidelines for reporting bugs, submitting pull requests, and adhering to code style standards.

meme-game/
├── backend/                       # Python 3 / Flask / Socket.IO Backend
│   ├── core/                      # Database connections, config, and GIPHY integration
│   ├── middleware/                # JWT authentication and guest authorization guards
│   ├── routes/                    # REST API routes and authoritative WebSocket handlers
│   ├── services/                  # SMTP email delivery, room logic, and account migration
│   ├── utils/                     # Room code generators, logging, and syntax helpers
│   ├── app.py                     # Flask application factory and CORS/Socket.IO bootstrap
│   └── requirements.txt           # Python dependency manifest
│
└── frontend/                      # React 18 / TypeScript / Vite Frontend
    ├── src/
    │   ├── components/
    │   │   ├── GamePhases/        # Isolated components for all 8 game phases
    │   │   ├── UI/                # Reusable Neo-Brutalist design system primitives
    │   │   ├── Chat.tsx           # Real-time room text chat
    │   │   └── ConnectionStatus.tsx # Live latency and reconnection indicator
    │   ├── context/               # Global authentication and WebSocket state providers
    │   ├── pages/                 # Top-level route pages (Lobby, Game, Dashboard, HowToPlay)
    │   ├── index.css              # Neo-Brutalist HSL tokens and Tailwind layer overrides
    │   └── main.tsx               # Application entry point
    └── package.json               # Node.js dependency manifest and NPM scripts

• Node.js (v18.0+)
• Python (v3.10+)
• MongoDB (Local instance or free cloud cluster via MongoDB Atlas)
• Redis (Optional): Local instance or serverless instance via Upstash

git clone https://github.com/subhash-22-codes/MemeGame.git
cd MemeGame

cd backend

# Create and activate Python virtual environment
python -m venv venv
# On Windows:
venv\Scripts\activate
# On macOS / Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create .env configuration
cp .env.example .env

# Start authoritative backend server
python app.py

cd ../frontend

# Install dependencies
npm install

# Create .env configuration
cp .env.example .env

# Start Vite development server
npm run dev

• 8-Phase Real-Time Game Loop: Authoritative room synchronization and timers.
• Community Ranked Voting: Blind ranked-choice scoring (🥇 5 pts, 🥈 3 pts, 🥉 1 pt).
• Guest Accounts & Migration: Instant guest play with 1-click registered account upgrade.
• Meme of the Match Card: Client-side Canvas generator for exportable PNG achievement plaques.
• Custom Prompt Decks: User-created prompt packs and themed expansion decks.
• Voice-to-Meme Mode: Web Speech API integration for spoken prompt creation.
• Tournament Rooms: Multi-table bracket support for 16–64 players.

We welcome contributions from developers of all skill levels. Please check our Contributing Guide for instructions on setting up your environment, running tests, and formatting pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Distributed under the MIT License. See LICENSE for more information.

• Giphy Developers for real-time GIF streaming APIs.
• DiceBear Avatars for dynamic SVG player avatars.
• Lucide React for crisp, consistent UI iconography.
• Flask-SocketIO for Python WebSocket room infrastructure.