Overview

# Overview

This is a multiplayer scrum poker game with a retro JRPG aesthetic that gamifies story point estimation. Players create or join lobbies, select fantasy avatar classes (warrior, wizard, etc.), and estimate Jira tickets by "battling" pixel art bosses. The game combines traditional scrum poker mechanics with engaging visual elements and real-time multiplayer interactions.

# User Preferences

Preferred communication style: Simple, everyday language.

# System Architecture

## Frontend Architecture
- **Framework**: React 18 with TypeScript and Vite for fast development
- **Styling**: Tailwind CSS with custom retro/pixel art CSS variables and animations
- **UI Components**: Radix UI primitives with custom retro-styled wrapper components
- **3D Graphics**: React Three Fiber with Drei for 3D avatar models and effects
- **State Management**: Zustand stores for game state, WebSocket connections, and audio
- **Real-time Communication**: Socket.IO client for multiplayer lobby management

## Backend Architecture
- **Server**: Express.js with TypeScript running in ESM mode
- **WebSocket**: Socket.IO server for real-time game events and lobby synchronization
- **Game Logic**: In-memory game state manager handling lobby creation, player management, and boss battles
- **Storage**: Configurable storage interface with in-memory implementation (ready for database integration)

## Data Storage
- **Database ORM**: Drizzle ORM configured for PostgreSQL with schema migrations
- **Current Implementation**: In-memory storage with Redis caching layer
- **Session Management**: Express sessions with PostgreSQL session store (connect-pg-simple)
- **Redis Caching**: Upstash Redis (cloud) via @upstash/redis for caching lobbies and player sessions (gracefully degrades if unavailable)

## Game State Management
- **Lobby System**: Dynamic lobby creation with unique invite codes and host privileges
- **Player Management**: Team assignment (developers, QA, spectators) with avatar class selection
- **Game Phases**: State machine handling lobby → avatar selection → battle → scoring → reveal cycles
- **Ticket Management**: Jira-style ticket estimation with Fibonacci scoring system

## Real-time Features
- **WebSocket Events**: Typed event system for lobby management, player actions, and game progression
- **Attack Animations**: Visual feedback system for player interactions with boss battles
- **Live Updates**: Real-time synchronization of player scores, game phases, and lobby state
- **Connection Stability**: 
  - Server ping every 20 seconds with 60s timeout (optimized for corporate proxies)
  - Client-side heartbeat every 25 seconds to prevent infrastructure idle timeouts
  - Connection state recovery buffers messages for 3 minutes during brief disconnects
  - Automatic reconnection with exponential backoff and token-based session restoration
  - Graceful handling of WebGL context loss during reconnection

## Audio System
- **Sound Management**: Zustand-based audio store with mute/unmute functionality
- **Game Audio**: Background music, hit effects, and success sounds with overlap support
- **User Control**: Client-side audio control with persistent mute preferences

## Development Tools
- **Build System**: Vite with React plugin, TypeScript checking, and ESBuild for production
- **Asset Support**: GLSL shaders, 3D models (GLTF/GLB), and audio files
- **Development Server**: Hot reload with runtime error overlay and request logging
- **Path Aliases**: Clean imports using @ for client code and @shared for common types

## Community & Feedback Management
- **GitHub Issue Templates**: Structured YAML forms for bug reports, feature requests, documentation, and performance issues
- **Pull Request Template**: Standardized PR format with type classification, testing checklist, and DCO agreement
- **Discussion Templates**: Community-driven feature voting and idea sharing via GitHub Discussions
- **Security Policy**: Private vulnerability reporting process with defined scope and timeline (.github/SECURITY.md)
- **Template Structure**: Uses 2025 best practices with auto-labeling, required fields, and dropdown validations

# External Dependencies

- **Database**: Neon PostgreSQL (serverless) via @neondatabase/serverless
- **Cache**: Upstash Redis (cloud) via @upstash/redis for lobby and session caching
- **WebSocket**: Socket.IO for real-time multiplayer communication
- **UI Framework**: Radix UI component primitives for accessible interface elements
- **3D Rendering**: React Three Fiber ecosystem for 3D graphics and animations
- **State Management**: Zustand for client-side state management
- **Styling**: Tailwind CSS with PostCSS for utility-first styling
- **Fonts**: Inter font family via @fontsource for consistent typography
- **Development**: Vite runtime error modal for enhanced debugging experience

# Licensing Structure

The project uses a comprehensive dual-licensing approach to protect intellectual property while maintaining open source principles:

## Core Licenses
- **Code**: GNU AGPL-3.0-or-later for all game logic, server, and client code
- **Assets**: Creative Commons CC BY-NC-ND 4.0 for all art, sprites, sounds, and media
- **Commercial**: Proprietary EULA for paid integrations and premium features
- **Trademarks**: "Scrum Monsters" name and branding protected as trademarks

## License Files Structure
- `LICENSE.md` - Main licensing summary and guide
- `licenses/AGPL-3.0-or-later.txt` - Full copyleft license text
- `licenses/CC-BY-NC-ND-4.0.txt` - Full Creative Commons license text  
- `licenses/Apache-2.0.txt` - Alternative permissive license text
- `commercial/EULA.txt` - Commercial end user license agreement
- `TRADEMARKS.md` - Trademark protection and usage guidelines
- `NOTICES.md` - Third-party software attributions
- `CONTRIBUTING.md` - Updated with DCO requirements for contributors

# Roadmap

## Priority 1: Connection Stability (High Impact)
- [x] **Visibility change handling** - Proactively check/restore connection when browser tab returns from background
- [x] **Visual reconnection indicators** - Show players a clear UI when connection is recovering (ReconnectionStatus component)
- [x] **Office network optimization** - Heartbeat 25s client, 20s server ping, 60s timeout (tuned for corporate proxies)

## Priority 2: Performance Optimization
- [x] **Lazy load heavy components** - Split 3D assets, battle screens, and avatar selection into separate chunks (React.lazy + Suspense)
- [x] **Batch WebSocket messages** - Server batches position updates every 100ms, client throttles to 100ms
- [x] **Optimize React re-renders** - React.memo added to SpriteRenderer, PlayerCharacter components

## Priority 3: Code Quality
- [ ] **Add React error boundaries** - Prevent full app crashes from component errors
- [ ] **Clean up unused variables** - Remove effectText and other dead code
- [ ] **Improve TypeScript types** - Replace `any` casted socket events with proper typed interfaces
- [ ] **Add structured logging** - Use log levels (debug/info/warn/error) for production debugging

## Priority 4: User Experience
- [ ] **Persist audio settings** - Save mute/volume preferences to localStorage
- [ ] **Loading states** - Add spinners/skeletons for lobby creation and joining
- [ ] **Mobile touch controls** - Improve battle controls for touchscreen devices
- [ ] **Keyboard shortcuts guide** - Show available controls during battle

## Priority 5: Reliability & Monitoring
- [ ] **Health check endpoint** - Add /health route for deployment monitoring
- [ ] **Production logging** - Structured logs for debugging connection issues
- [ ] **Error tracking** - Consider Sentry or similar for production error monitoring
- [ ] **Performance metrics** - Track WebSocket latency and reconnection rates

## Completed
- [x] WebSocket reconnection cleanup (fixed duplicate socket issue)
- [x] Upstash Redis caching for lobbies and sessions
- [x] Office network heartbeat optimization (25s client, 20s server)
- [x] Removed verbose player movement console.logs
- [x] Visibility change handling (auto-reconnect when tab returns from background)
- [x] Visual reconnection indicators (ReconnectionStatus banner component)