Delete outdated ARCHITECTURE.md file, and unused old favicon
This commit is contained in:
parent
7d124d1ae9
commit
6baa194e5b
341
ARCHITECTURE.md
341
ARCHITECTURE.md
|
|
@ -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
|
||||
BIN
favicon.ico
BIN
favicon.ico
Binary file not shown.
|
Before Width: | Height: | Size: 66 KiB |
Loading…
Reference in New Issue