diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 7a64e43..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,341 +0,0 @@ -# Gomoku Game Design Document - -## 1. Overview - -A simple turn-based multiplayer Gomoku (Five-in-a-Row) web game for casual play between friends. The system prioritizes simplicity and ease of deployment over scalability. - -## 2. Tech Stack - -- **Backend:** Elysia (Bun runtime) -- **Frontend:** HTML/CSS/TypeScript + HTMX -- **Real-time communication:** WebSockets (Elysia built-in) -- **Database:** SQLite with Bun:sqlite - -## 3. System Requirements - -### 3.1 Functional Requirements - -**FR1: Game Creation** - -- The system SHALL allow players to create new game sessions -- The system SHALL generate unique game IDs for each session -- The system SHALL support maximum 2 players per game - -**FR2: Player Connection** - -- The system SHALL establish WebSocket connections for real-time communication -- The system SHALL handle player disconnection gracefully -- The system SHALL allow players to reconnect to existing games - -**FR3: Game Logic** - -- The system SHALL implement standard Gomoku rules (15x15 board) -- The system SHALL detect win conditions (5 stones in a row: horizontal, vertical, diagonal) -- The system SHALL validate moves (prevent placing stones on occupied positions) -- The system SHALL enforce turn-based play - -**FR4: Real-time Updates** - -- The system SHALL broadcast moves to all connected players immediately -- The system SHALL notify players of game state changes (turn, win, draw) -- The system SHALL update UI in real-time without page refresh - -### 3.2 Non-Functional Requirements - -**NFR1: Performance** - -- The system SHALL respond to moves within 100ms -- The system SHALL support concurrent games (minimum 10 simultaneous games) - -**NFR2: Usability** - -- The system SHALL provide intuitive click-to-place stone interaction -- The system SHALL display current turn indicator -- The system SHALL show game status (waiting, playing, finished) - -**NFR3: Reliability** - -- The system SHALL maintain game state during temporary disconnections -- The system SHALL prevent cheating through client-side validation bypass - -## 4. System Architecture - -### 4.1 High-Level Architecture - -``` -┌─────────────────┐ WebSocket ┌─────────────────┐ -│ Client A │◄─────────────► │ │ -│ (Browser) │ │ Elysia │ -└─────────────────┘ │ Server │ - │ │ -┌─────────────────┐ WebSocket │ │ -│ Client B │◄─────────────► │ │ -│ (Browser) │ └─────────────────┘ -└─────────────────┘ │ - │ - ┌─────────────────┐ - │ SQLite DB │ - │ (Optional) │ - └─────────────────┘ -``` - -### 4.2 Component Design - -#### 4.2.1 Server Components - -**GameManager** - -- Responsibilities: Create/destroy games, manage active game instances, handle matchmaking -- Interface: - ```typescript - createGame(): GameInstance - joinGame(gameId: string, playerId: string): boolean - getGame(gameId: string): GameInstance | null - removeGame(gameId: string): void - ``` - -**GameInstance** - -- Responsibilities: Maintain game state, validate moves, detect win conditions -- State: - ```typescript - { - id: string - board: (null | 'black' | 'white')[][] - currentPlayer: 'black' | 'white' - status: 'waiting' | 'playing' | 'finished' - winner: null | 'black' | 'white' | 'draw' - players: { black?: string, white?: string } - } - ``` - -**WebSocketHandler** - -- Responsibilities: Manage connections, route messages, handle disconnections -- Message Types: - - ```typescript - // Client → Server - { type: 'join_game', gameId: string, playerId: string } - { type: 'make_move', row: number, col: number } - { type: 'ping' } - - // Server → Client - { type: 'game_state', state: GameState } - { type: 'move_result', success: boolean, error?: string } - { type: 'player_joined', playerId: string } - { type: 'player_disconnected', playerId: string } - ``` - -#### 4.2.2 Client Components - -**GameBoardUI** - -- Responsibilities: Render 15x15 grid, handle stone placement clicks -- The component SHALL highlight the last move -- The component SHALL show stone colors (black/white) -- The component SHALL disable interaction when not player's turn - -**GameStateManager** - -- Responsibilities: Track local game state, sync with server updates -- The component SHALL maintain local copy of game state -- The component SHALL handle optimistic updates with rollback capability - -**WebSocketClient** - -- Responsibilities: Manage WebSocket connection, send/receive messages -- The component SHALL automatically reconnect on connection loss -- The component SHALL queue messages during disconnection - -## 5. API Design - -### 5.1 WebSocket Messages - -**Join Game Request** - -```json -{ - "type": "join_game", - "gameId": "optional-game-id", - "playerId": "player-uuid" -} -``` - -**Make Move Request** - -```json -{ - "type": "make_move", - "row": 7, - "col": 7 -} -``` - -**Game State Update** - -```json -{ - "type": "game_state", - "state": { - "id": "game-uuid", - "board": "15x15 array", - "currentPlayer": "black", - "status": "playing", - "winner": null, - "players": { - "black": "player1-uuid", - "white": "player2-uuid" - } - } -} -``` - -### 5.2 HTTP Endpoints (HTMX) - -**GET /** - -- Returns main game interface HTML - -**GET /game/:gameId** - -- Returns game-specific interface (for sharing game links) - -## 6. Database Schema - -### 6.1 Tables (Optional - MVP can work without persistence) - -**games** - -```sql -CREATE TABLE games ( - id TEXT PRIMARY KEY, - board TEXT NOT NULL, -- JSON serialized board - current_player TEXT NOT NULL, - status TEXT NOT NULL, - winner TEXT, - created_at INTEGER NOT NULL, - updated_at INTEGER NOT NULL -); -``` - -**players** - -```sql -CREATE TABLE players ( - id TEXT PRIMARY KEY, - name TEXT, - created_at INTEGER NOT NULL -); -``` - -**game_players** - -```sql -CREATE TABLE game_players ( - game_id TEXT NOT NULL, - player_id TEXT NOT NULL, - color TEXT NOT NULL, -- 'black' or 'white' - FOREIGN KEY (game_id) REFERENCES games(id), - FOREIGN KEY (player_id) REFERENCES players(id), - PRIMARY KEY (game_id, player_id) -); -``` - -## 7. User Flow - -### 7.1 Happy Path - -1. Player A opens game URL -2. System creates new game, assigns Player A as 'black' -3. Player A shares game link with Player B -4. Player B joins game, assigned as 'white' -5. Game starts, Player A (black) makes first move -6. Players alternate turns until win/draw condition -7. System displays game result - -### 7.2 Error Scenarios - -**Player Disconnection** - -- The system SHALL maintain game state for 5 minutes -- The system SHALL notify remaining player of disconnection -- The system SHALL allow reconnection using same player ID - -**Invalid Move** - -- The system SHALL reject invalid moves -- The system SHALL send error message to client -- The system SHALL maintain current game state - -## 8. Security Considerations - -### 8.1 Move Validation - -- The system SHALL validate all moves server-side -- The system SHALL prevent players from making moves out of turn -- The system SHALL prevent overwriting existing stones - -### 8.2 Game Integrity - -- The system SHALL generate cryptographically secure game IDs -- The system SHALL prevent players from joining games they're not invited to -- The system SHALL rate-limit move requests to prevent spam - -## 9. Deployment - -### 9.1 Development Environment - -```bash -# Start development server -bun run dev - -# Run tests -bun test - -# Build for production -bun run build -``` - -### 9.2 Production Considerations - -- Single server deployment (no load balancing needed) -- SQLite database file backup strategy -- Environment variable configuration -- Basic logging for debugging - -## 10. Future Enhancements - -### 10.1 Phase 2 Features - -- Spectator mode -- Game replay functionality -- Player statistics tracking -- Tournament bracket system - -### 10.2 Technical Improvements - -- Redis for session management (multi-server support) -- Move history with undo functionality -- AI opponent option -- Mobile-responsive design optimization - -## 11. Testing Strategy - -### 11.1 Unit Tests - -- Game logic validation (win detection, move validation) -- WebSocket message handling -- Database operations (if implemented) - -### 11.2 Integration Tests - -- End-to-end game flow -- Multi-player scenarios -- Reconnection handling - -### 11.3 Manual Testing - -- Cross-browser compatibility -- Network interruption scenarios -- Simultaneous player actions diff --git a/favicon.ico b/favicon.ico deleted file mode 100755 index 02cc8f9..0000000 Binary files a/favicon.ico and /dev/null differ