Skip to content

WARP.md

Latest commit

 

History

History
418 lines (356 loc) · 15.4 KB

WARP.md

File metadata and controls

418 lines (356 loc) · 15.4 KB

LookUp.Cafe - Project Overview

Project Identity

Name: lookup.cafe
Type: Multiplayer Gaming & Hangout Platform
Tech Stack: React 19, TypeScript, Vite, Material-UI, Socket.io
Backend API: https://api.ventures.isharehow.app
Environment: AlmaLinux, Apache web server

Project Description

LookUp.Cafe is a real-time multiplayer platform for playing mini-games and hanging out with family & friends. The application features interactive games (guessing, drawing, puzzles) and a video hangout space.

Current Directory Structure

/home/ishaglcy/public_html/lookup.cafe/
├── dist/                    # Build output (Apache serves from here)
│   ├── assets/
│   ├── index.html
│   └── vite.svg
├── node_modules/           # Dependencies (167 packages)
├── public/                 # Static assets
├── src/
│   ├── components/
│   │   ├── game/
│   │   │   ├── ChatPanel.tsx         # In-game chat functionality
│   │   │   ├── DebugPanel.tsx        # Debug tools for development
│   │   │   ├── DrawingGame.tsx       # Canvas-based drawing game (10.9KB)
│   │   │   ├── GameLobby.tsx         # Main lobby for creating/joining rooms (15KB)
│   │   │   ├── GameRoom.tsx          # Room management component (8.2KB)
│   │   │   ├── GameTypeSelection.tsx # Game type picker (5.6KB)
│   │   │   ├── GuessingGame.tsx      # Guessing game with voting (31.6KB - largest component)
│   │   │   └── PuzzleGame.tsx        # Puzzle game implementation (7.6KB)
│   │   └── AppShell.tsx              # Main app layout wrapper
│   ├── hooks/
│   │   └── useGameSocket.ts          # Socket.io integration hook with game state management
│   ├── types/
│   │   └── game.ts                   # TypeScript type definitions for game logic
│   ├── utils/
│   │   └── socket.ts                 # Socket.io client initialization and utilities
│   ├── views/
│   │   ├── GameView.tsx              # Main game view (renders GameLobby)
│   │   └── HangView.tsx              # Video hangout view with notes
│   ├── App.tsx                       # Root app component with routing
│   ├── App.css                       # App-level styles
│   ├── main.tsx                      # React entry point
│   └── index.css                     # Global styles
├── .env                              # Environment variables (backend URL)
├── .htaccess                         # Apache config for SPA routing
├── index.html                        # HTML entry point
├── package.json                      # Dependencies and scripts
├── package-lock.json
├── tsconfig.json                     # TypeScript config (base)
├── tsconfig.app.json                 # App-specific TS config
├── tsconfig.node.json                # Node-specific TS config
├── vite.config.ts                    # Vite build configuration
├── eslint.config.js                  # ESLint configuration
├── README.md                         # Vite + React template docs
└── look.code-workspace               # VS Code workspace file

Key Dependencies

Production

  • react: ^19.2.0 (latest)
  • react-dom: ^19.2.0
  • react-router-dom: ^7.10.1 (client-side routing)
  • @mui/material: ^5.18.0 (UI components)
  • @mui/icons-material: ^5.18.0
  • @emotion/react: ^11.14.0 (MUI peer dependency)
  • @emotion/styled: ^11.14.1
  • socket.io-client: ^4.8.1 (real-time WebSocket communication)

Development

  • typescript: ~5.9.3
  • vite: ^7.2.4
  • @vitejs/plugin-react: ^5.1.1
  • eslint: ^9.39.1 with TypeScript support
  • @types/react: ^19.2.5
  • @types/react-dom: ^19.2.3
  • @types/node: ^24.10.4

Application Architecture

Routing

The app uses React Router with the following routes:

  • / → redirects to /game
  • /game → Main game lobby and gameplay
  • /hang → Video hangout view

Socket.io Integration

Connection: Established in App.tsx to https://api.ventures.isharehow.app Config:

  • Auto-reconnection enabled
  • 1-5 second reconnection delay
  • Max 5 reconnection attempts

Custom Hook: useGameSocket manages:

  • Connection state (isConnected, error, socketId)
  • Game room state (gameRoom, players)
  • Actions: createRoom, joinRoom, leaveRoom, setGameType, startGame
  • Game-specific actions: submitAnswer, sendDrawing, clearCanvas
  • Guessing game: setSecretWords, submitGuess, voteForGuess, nextGuessingRound

Socket Events: The hook listens to 20+ events including:

  • Connection: connect, disconnect, connect_error
  • Room: room-created, room-joined, player-joined, player-left
  • Game flow: started, state-update, round-start, round-end, type-set, finished
  • Guessing: words-set, guess-submitted, phase-changed, vote-received, voting-complete, round-started
  • Errors: game:error

Game Types

Defined in src/types/game.ts:

  1. Guessing - Players submit guesses, vote on best answers, earn points
  2. Drawing - Canvas-based drawing with real-time stroke sharing
  3. Puzzle - Collaborative puzzle solving

Game States & Flow

States: lobby → playing → roundEnd → gameEnd
Round Phases (Guessing): guessing → voting → results

Theme

Custom MUI theme with:

  • Primary color: #4B5DBD (purple-blue)
  • Inter font family
  • Rounded corners (8px buttons, 12px papers)
  • Light mode

Components

GameLobby (15KB)

  • Create/join room interface
  • Custom room codes
  • Active rooms list (currently fetched but not displayed)
  • Player name input
  • Transitions to GameRoom when joined

GameRoom (8.2KB)

  • Displays current players with scores
  • Game type selection
  • Start game button (host only)
  • Routes to appropriate game component based on gameType
  • Shows current round/max rounds

GuessingGame (31.6KB - most complex)

  • Multi-phase gameplay: guessing → voting → results
  • Secret word assignment per player
  • Timer-based rounds
  • Real-time guess submission
  • Voting system for best answers
  • Score tracking and leaderboard
  • DebugPanel integration

DrawingGame (10.9KB)

  • HTML5 Canvas drawing interface
  • Real-time stroke broadcasting
  • Color picker (multiple colors)
  • Brush width control
  • Clear canvas functionality
  • Guess submission via text input
  • Timer display
  • Player list with scores

PuzzleGame (7.6KB)

  • Placeholder implementation
  • Basic structure ready for puzzle logic

HangView

  • Video call link input/sharing
  • Shared notes textarea
  • Tab navigation (Hang Dash, Game Dash)
  • Right panel with Archive/Shared/Game tabs
  • Join call button (opens in new tab)

ChatPanel & DebugPanel

  • Reusable components for debugging and chat
  • Integrated into game views

Type System

Comprehensive TypeScript definitions in src/types/game.ts:

  • GameType: 'guessing' | 'drawing' | 'puzzle'
  • GameState: 'lobby' | 'playing' | 'roundEnd' | 'gameEnd'
  • RoundPhase: 'guessing' | 'voting' | 'results'
  • Player: id, name, score, isHost, isActive, avatar?, userId?
  • GameRoom: Complete room state with all game data
  • DrawingStroke: Canvas drawing data structure
  • GuessSubmission, RoundResult: Game-specific data types
  • Socket Event Payloads: CreateRoomData, JoinRoomData, StartGameData, SubmitAnswerData

Build & Deployment

Scripts

"dev": "vite"           // Development server on port 5173
"build": "tsc -b && vite build"  // Type-check + build to dist/
"lint": "eslint ."      // Lint all files
"preview": "vite preview"  // Preview production build

Build Configuration

  • Output: dist/ directory
  • Assets: dist/assets/
  • Source maps: Disabled
  • Server: Port 5173, host: true (network accessible)

Apache Configuration (.htaccess)

  • Serves files from dist/ directory
  • SPA fallback routing to dist/index.html
  • Handles React Router client-side routing

Last Build

  • Build date: December 17, 2025 01:51
  • Files: index.html, vite.svg, assets/ folder
  • Built artifacts present in dist/

Current State & Status

✅ Complete

  • Basic project structure
  • Socket.io client integration
  • Game lobby with room creation/joining
  • Three game types with UI implementations
  • Real-time multiplayer foundation
  • Type-safe TypeScript throughout
  • Material-UI theming
  • Client-side routing
  • Apache deployment configuration
  • Build pipeline

⚠️ Needs Attention

  • Backend connection: Needs verification that backend API is running and accessible
  • Game testing: Multiplayer game flow needs end-to-end testing
  • HangView: Video integration incomplete (link sharing only, no WebRTC)
  • Active rooms list: Fetched but not displayed in GameLobby
  • PuzzleGame: Implementation incomplete/placeholder
  • Error handling: Could be more robust throughout
  • Loading states: Some components lack loading indicators
  • Chat functionality: ChatPanel exists but integration unclear
  • DebugPanel: Should be removable/hideable in production

🔧 Technical Debt

  • README.md is still Vite template boilerplate
  • No tests (no test framework setup)
  • No CI/CD configuration
  • Missing environment variable validation
  • Socket reconnection logic could be more sophisticated
  • No offline mode handling
  • Large component files (GuessingGame 31KB) could be refactored

🐛 Potential Issues

  1. Socket connection: App initializes socket in App.tsx before component mount - could cause issues
  2. Environment variables: .env file readable, contains backend URL (not sensitive but should verify)
  3. Type safety: Some any types in game.ts (guesses, votes)
  4. Error boundaries: No React error boundaries implemented
  5. Memory leaks: Socket event listeners may not clean up properly on unmount
  6. Build permissions: dist/ owned by root, could cause deployment issues

Environment & Hosting

Server: AlmaLinux with Apache
User: ishaglcy
Path: /home/ishaglcy/public_html/lookup.cafe
Domain: Presumably lookup.cafe (not verified)
Backend: api.ventures.isharehow.app

Shell: zsh 5.5.1
Node version: Not checked but required for Vite
Permission issues: dist/ and node_modules/ owned by root (should verify)

Next Steps & Recommendations

Immediate (Get Working)

  1. Verify backend connection: Test if socket connects to api.ventures.isharehow.app
  2. Check build: Run npm run build to ensure clean build
  3. Test deployment: Access via web browser, check console for errors
  4. Verify Apache: Confirm .htaccess is processing correctly
  5. Permission audit: Fix file ownership if needed (ishaglcy vs root)

Short-term (Core Functionality)

  1. Implement full game flow testing with 2+ players
  2. Complete PuzzleGame implementation
  3. Add proper error handling and user feedback
  4. Implement active rooms display
  5. Add loading states throughout
  6. Fix any Socket.io event listener cleanup issues

Medium-term (Polish)

  1. Complete video call integration (WebRTC or iframe embed)
  2. Add user authentication/accounts
  3. Implement persistent game history
  4. Add avatar customization
  5. Mobile responsive testing and fixes
  6. Add accessibility improvements
  7. Remove/hide DebugPanel in production
  8. Refactor large components (GuessingGame)

Long-term (Scale & Maintain)

  1. Add test suite (Jest + React Testing Library)
  2. Set up CI/CD pipeline
  3. Add analytics and monitoring
  4. Performance optimization
  5. SEO improvements
  6. Add more game types
  7. Implement chat moderation
  8. Add game replays/spectator mode

Dependencies to Install

None currently - all dependencies in package.json are installed in node_modules/

Known Files That Need Creation

  • Comprehensive README.md (current one is template)
  • .gitignore verification (exists but contents not checked)
  • Testing configuration
  • CI/CD configuration
  • Environment variable documentation

Document Created: December 20, 2025
Last Updated: December 20, 2025
Status: Initial assessment - ready for development/debugging

Backend Implementation (Added December 20, 2025)

Backend Stack

  • Framework: Flask 2.3.3 + Flask-SocketIO 5.3.6
  • Database: SQLite (with MariaDB support ready)
  • Real-time: Socket.IO with eventlet async mode
  • ORM: SQLAlchemy 2.0.36
  • CORS: Flask-CORS for frontend integration

Directory Structure

backend/
├── app.py                    # Main Flask + Socket.IO server (500+ lines)
├── models.py                 # SQLAlchemy database models
├── config.py                 # Configuration management
├── requirements.txt          # Python dependencies
├── .env                      # Environment variables
├── start.sh                  # Startup script
├── README.md                 # Backend documentation
├── venv/                     # Python virtual environment
├── instance/
│   └── lookup.db            # SQLite database (36KB)
└── game_content/
    ├── drawing_words.json   # 330 drawing words
    └── puzzles.json         # 50 puzzles

Database Models

  • GameRoom: Room state, game type, rounds, host info
  • GamePlayer: Player info, scores, active status
  • GameRound: Round history and results
  • PlayerStats: Aggregate player statistics

API Endpoints

  • GET / - Health check
  • GET /health - Health with database status
  • GET /api/rooms - List active game rooms

Socket.IO Events

Client → Server: create-room, join-room, leave-room, set-type, start, submit-answer, draw, clear, set-words, submit-guess, vote Server → Client: connected, room-created, room-joined, player-joined, player-left, type-set, started, round-start, round-end, correct-answer, error, draw, clear, words-set, guess-submitted, vote-received

Game Features

  • In-memory game state for performance (with DB persistence ready)
  • 330 drawing words across difficulty levels
  • 50 puzzles for puzzle game mode
  • Real-time synchronization via Socket.IO
  • Auto-reconnection with configurable retry logic
  • CORS configured for localhost:5173 and lookup.cafe

Current Status

  • ✅ Backend server running successfully
  • ✅ Database initialized (SQLite at backend/instance/lookup.db)
  • ✅ Game content loaded (330 words, 50 puzzles)
  • ✅ Socket.IO server operational on port 5000
  • ✅ HTTP endpoints responding correctly
  • ✅ Frontend configured to connect to localhost:5000
  • ⏳ SystemD service ready (not yet installed)
  • ⏳ Apache reverse proxy not configured
  • ⏳ MariaDB migration pending (currently using SQLite)

Running the Backend

Development:

cd backend
source venv/bin/activate
python app.py

Production (SystemD):

sudo cp /tmp/lookup-backend.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable lookup-backend
sudo systemctl start lookup-backend

Next Steps

  1. Install and configure systemd service for auto-start
  2. Set up Apache reverse proxy for production deployment
  3. Migrate from SQLite to MariaDB (optional)
  4. Test full game flow with frontend
  5. Configure SSL/HTTPS for production
  6. Set up log rotation
  7. Add monitoring and alerts

Configuration

Backend URL: http://localhost:5000 (dev) or via Apache proxy (prod) Frontend points to: VITE_BACKEND_URL in .env Database: SQLite at backend/instance/lookup.db (36KB) Logs: stdout/stderr (systemd journal when using service)
⚡