chess/planning/implementation/file-structure.md

Chess Game - Complete File Structure

Project Overview

Complete file structure for the HTML chess game with single-player functionality.

Directory Layout

chess-game/
├── index.html                          # Main entry point
├── README.md                           # Project documentation
├── package.json                        # NPM configuration (optional)
│
├── css/
│   ├── main.css                        # Global styles and layout
│   ├── board.css                       # Chessboard styling
│   ├── pieces.css                      # Chess piece styling
│   ├── game-controls.css               # UI controls styling
│   └── animations.css                  # Move and capture animations
│
├── js/
│   ├── main.js                         # Application entry point
│   │
│   ├── models/
│   │   ├── Board.js                    # Board state representation
│   │   ├── Piece.js                    # Base piece class
│   │   ├── pieces/
│   │   │   ├── Pawn.js                 # Pawn movement logic
│   │   │   ├── Rook.js                 # Rook movement logic
│   │   │   ├── Knight.js               # Knight movement logic
│   │   │   ├── Bishop.js               # Bishop movement logic
│   │   │   ├── Queen.js                # Queen movement logic
│   │   │   └── King.js                 # King movement logic
│   │   └── GameState.js                # Game state manager
│   │
│   ├── controllers/
│   │   ├── GameController.js           # Main game controller
│   │   ├── MoveController.js           # Move execution controller
│   │   └── AIController.js             # Computer opponent logic
│   │
│   ├── views/
│   │   ├── BoardView.js                # Board rendering
│   │   ├── PieceView.js                # Piece rendering
│   │   └── UIManager.js                # UI state management
│   │
│   ├── engine/
│   │   ├── MoveValidator.js            # Move legality checker
│   │   ├── RuleEngine.js               # Chess rules implementation
│   │   ├── CheckDetector.js            # Check/checkmate detection
│   │   ├── MoveGenerator.js            # Valid move generation
│   │   └── AIEngine.js                 # AI decision making
│   │
│   └── utils/
│       ├── Constants.js                # Game constants
│       ├── Helpers.js                  # Utility functions
│       └── EventBus.js                 # Event communication
│
├── assets/
│   ├── pieces/                         # Chess piece images/sprites
│   │   ├── white-pawn.svg
│   │   ├── white-rook.svg
│   │   ├── white-knight.svg
│   │   ├── white-bishop.svg
│   │   ├── white-queen.svg
│   │   ├── white-king.svg
│   │   ├── black-pawn.svg
│   │   ├── black-rook.svg
│   │   ├── black-knight.svg
│   │   ├── black-bishop.svg
│   │   ├── black-queen.svg
│   │   └── black-king.svg
│   └── sounds/                         # Sound effects (optional)
│       ├── move.mp3
│       ├── capture.mp3
│       └── check.mp3
│
└── tests/
    ├── models/
    │   ├── Board.test.js
    │   ├── Piece.test.js
    │   └── GameState.test.js
    ├── engine/
    │   ├── MoveValidator.test.js
    │   ├── RuleEngine.test.js
    │   └── CheckDetector.test.js
    └── integration/
        └── game-flow.test.js

File Responsibilities

Core Files

• index.html: HTML structure, board layout, UI controls
• main.js: Application initialization, dependency injection

Models (Data Layer)

• Board.js: 8x8 grid representation, piece positions
• Piece.js: Base class with common piece properties
• pieces/*.js: Individual piece movement patterns
• GameState.js: Turn tracking, captured pieces, game status

Controllers (Business Logic)

• GameController.js: Game lifecycle, turn management
• MoveController.js: Move execution, validation orchestration
• AIController.js: Computer opponent decision making

Views (Presentation Layer)

• BoardView.js: Render board, squares, coordinates
• PieceView.js: Render pieces, drag-and-drop handling
• UIManager.js: Buttons, status display, modals

Engine (Game Logic)

• MoveValidator.js: Check if moves are legal
• RuleEngine.js: Chess rules (castling, en passant, promotion)
• CheckDetector.js: Detect check, checkmate, stalemate
• MoveGenerator.js: Generate all valid moves for a position
• AIEngine.js: Minimax/alpha-beta pruning for AI

Utilities

• Constants.js: Colors, piece types, board size
• Helpers.js: Coordinate conversion, array utilities
• EventBus.js: Component communication

Implementation Order

1. Phase 1: Foundation

   • Constants.js
   • Helpers.js
   • EventBus.js

2. Phase 2: Models

   • Board.js
   • Piece.js
   • Individual pieces (Pawn → Rook → Knight → Bishop → Queen → King)
   • GameState.js

3. Phase 3: Engine

   • MoveValidator.js
   • MoveGenerator.js
   • RuleEngine.js
   • CheckDetector.js

4. Phase 4: Views

   • BoardView.js
   • PieceView.js
   • UIManager.js

5. Phase 5: Controllers

   • MoveController.js
   • GameController.js
   • AIController.js

6. Phase 6: Integration

   • main.js
   • index.html
   • CSS files

Dependencies Map

GameController
├── GameState
├── Board
├── MoveController
│   ├── MoveValidator
│   ├── RuleEngine
│   └── CheckDetector
├── AIController
│   ├── AIEngine
│   └── MoveGenerator
└── UIManager
    ├── BoardView
    └── PieceView

File Size Guidelines

• Models: 100-200 lines each
• Controllers: 200-300 lines each
• Views: 150-250 lines each
• Engine: 200-400 lines each
• Utilities: 50-150 lines each

Naming Conventions

• Classes: PascalCase (e.g., GameController)
• Files: Match class name (e.g., GameController.js)
• Methods: camelCase (e.g., makeMove())
• Constants: UPPER_SNAKE_CASE (e.g., BOARD_SIZE)
• Private methods: Prefix with _ (e.g., _validateMove())

Module Pattern

All files use ES6 modules:

// Export
export class ClassName { }
export default ClassName;

// Import
import ClassName from './ClassName.js';
import { helper } from './Helpers.js';