# peter-abah/rb_chess architecture

> Architecture diagram of the GitHub repository peter-abah/rb_chess, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/peter-abah/rb_chess
- Repository: https://github.com/peter-abah/rb_chess

## Overview

##### Project type and purpose
- This is an open-source Ruby library (gem) that implements a full chess engine (rules, move generation/validation, serialization) and provides a command-line interface (CLI) for playing games.
- It exposes a public API (RbChess::Game, Board, Move, etc.) and a CLI entry point (bin/rb_chess → RbChess::CLI::CLI).

##### Main architectural components
a. Core Engine
- RbChess::Game
- RbChess::Board
- RbChess::Position
- RbChess::Move, MoveSet
- RbChess::Pieces (king, queen, rook, bishop, knight, pawn, piece_constants)
- RbChess::GameModules
- MoveGenerator
- MoveParser
- MoveValidator
- CastlingRights, FenParser, Errors
b. Serialization layer
- FEN parser/generator
- JSON and binary serialization (GameSaver)
c. CLI Layer
- bin/rb_chess (executable stub)
- RbChess::CLI::CLI (main loop, user input)
- RbChess::CLI::Players (player abstractions)
- RbChess::CLI::GameSaver (persist/restore game state)
d. Test Suite (RSpec)
- spec/* mirror core structure

##### Component relationships and data flow
- CLI → invokes → Game
- Game → composes → Board + Position + CastlingRights
- When `make_move` is called:
- MoveParser parses string → Move object
- MoveValidator checks legality against Board + GameModules
- MoveGenerator produces all possible moves
- Board updates Position + Pieces
- Game updates turn, move history
- Serialization:
- GameSaver ↔ Game (to_fen, from_fen, to_json, from_json, to_binary, from_binary)
- FENParser is used by both core and CLI to load/save state

##### Architectural patterns and design principles
- Modular design: Each responsibility isolated into its own file/namespace (Single Responsibility Principle)
- Use of Ruby modules to namespace components (RbChess, RbChess::CLI, RbChess::GameModules)
- Layered architecture: Core engine layer → Serialization layer → CLI layer
- Dependency inversion: high-level CLI depends on abstractions (Game API) rather than low-level modules

##### Elements
- Clear labels for each component (use class/module names)
- User input → CLI::CLI
- CLI::CLI → Game API
- Game → Board, MoveParser, MoveValidator, MoveGenerator
- GameSaver ↔ Game
- Core engine → FENParser
- Blue rectangles for core engine modules
- Green for CLI components
- Yellow for serialization/FENParser

## Diagram (Mermaid)

```mermaid
flowchart TB
    User((User/Console)):::external

    subgraph "CLI Layer"
        CLIStub["bin/rb_chess"]:::cli
        CLI["RbChess::CLI::CLI"]:::cli
        Players["RbChess::CLI::Players"]:::cli
        CLI_GameSaver["RbChess::CLI::GameSaver"]:::cli
        LetterDisplay["RbChess::LetterDisplay"]:::cli
        CLIStub --> CLI
        User --> CLIStub
        CLI --> Players
        CLI --> CLI_GameSaver
        CLI --> LetterDisplay
    end

    subgraph "Core Engine Layer"
        Game["RbChess::Game"]:::core
        Board["RbChess::Board"]:::core
        Position["RbChess::Position"]:::core
        Castling["RbChess::CastlingRights"]:::core
        Move["RbChess::Move"]:::core
        MoveSet["RbChess::MoveSet"]:::core
        subgraph "Pieces"
            King["king"]:::core
            Queen["queen"]:::core
            Rook["rook"]:::core
            Bishop["bishop"]:::core
            Knight["knight"]:::core
            Pawn["pawn"]:::core
            Piece["piece/base"]:::core
            PieceConst["piece_constants"]:::core
        end
        subgraph "GameModules"
            Gen["MoveGenerator"]:::core
            Parser["MoveParser"]:::core
            Validator["MoveValidator"]:::core
        end
        Errors["RbChess::Errors"]:::core
        Game --> Board
        Game --> Position
        Game --> Castling
        Game --> Move
        Game --> MoveSet
        Game --> Gen
        Game --> Parser
        Game --> Validator
        Game --> Errors
    end

    subgraph "Serialization Layer"
        FEN["RbChess::FenParser"]:::serial
        Serializer["GameSaver (JSON/Binary)"]:::serial
        FEN --> Serializer
        Game --> FEN
        Serializer --> Game
    end

    subgraph "Test Suite"
        direction LR
        spec["spec/"]:::test
        spec --> Board
        spec --> Position
        spec --> Move
        spec --> MoveSet
        spec --> King
        spec --> Queen
        spec --> Rook
        spec --> Bishop
        spec --> Knight
        spec --> Pawn
        spec --> Gen
        spec --> Parser
        spec --> Validator
        spec --> FEN
        spec --> Game
    end

    click Game "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/game.rb"
    click Board "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/board.rb"
    click Position "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/position.rb"
    click Move "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/move.rb"
    click MoveSet "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/move_set.rb"
    click King "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/pieces/king.rb"
    click Queen "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/pieces/queen.rb"
    click Rook "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/pieces/rook.rb"
    click Bishop "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/pieces/bishop.rb"
    click Knight "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/pieces/knight.rb"
    click Pawn "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/pieces/pawn.rb"
    click Piece "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/pieces/piece.rb"
    click PieceConst "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/pieces/piece_constants.rb"
    click Castling "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/castling_rights.rb"
    click FEN "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/fen_parser.rb"
    click Errors "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/errors.rb"
    click Gen "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/game_modules/move_generator.rb"
    click Parser "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/game_modules/move_parser.rb"
    click Validator "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/game_modules/move_validator.rb"
    click CLIStub "https://github.com/peter-abah/rb_chess/tree/main/bin/rb_chess"
    click CLI "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/cli/cli.rb"
    click Players "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/cli/players.rb"
    click CLI_GameSaver "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/cli/game_saver.rb"
    click LetterDisplay "https://github.com/peter-abah/rb_chess/blob/main/lib/rb_chess/letter_display.rb"
    click spec "https://github.com/peter-abah/rb_chess/tree/main/spec/"

    classDef core fill:#dae8fc,stroke:#6c8ebf
    classDef cli fill:#d5e8d4,stroke:#82b366
    classDef serial fill:#fff2cc,stroke:#d6b656
    classDef test fill:#f5f5f5,stroke:#999,stroke-dasharray:5 5
    classDef external fill:#ffffff,stroke:#000,stroke-dasharray:2 2
```
