From 6baa194e5b60a1f55a8b18c17fea7d3778e418bd Mon Sep 17 00:00:00 2001 From: sepia Date: Fri, 18 Jul 2025 12:13:59 -0500 Subject: [PATCH] Delete outdated ARCHITECTURE.md file, and unused old favicon --- ARCHITECTURE.md | 341 ------------------------------------------------ favicon.ico | Bin 67646 -> 0 bytes 2 files changed, 341 deletions(-) delete mode 100644 ARCHITECTURE.md delete mode 100755 favicon.ico 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 02cc8f9bb937857a8d3fec1b2e5c22e4730bca35..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 67646 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