chess/docs/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:
```javascript
// Export
export class ClassName { }
export default ClassName;

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