# jaws-1684/chess architecture

> Architecture diagram of the GitHub repository jaws-1684/chess, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jaws-1684/chess
- Repository: https://github.com/jaws-1684/chess

## Overview

##### Project Type and Purpose
- This is a Ruby-based command-line Chess engine and library.
- Provides core domain logic for Chess: board state, piece behaviors, game rules, move validation, serialization and display.
- Exposes a CLI entrypoint (`bin/chess`) for users to start/play games.

##### File Structure Analysis
- Top-level:
- bin/             → CLI executable
- lib/             → core library code under `lib/chess`
- spec/            → RSpec tests for each domain class
- old_files/       → previous version/archive (not part of current runtime)
- Gemfile, LICENSE, README.md
- Under `lib/chess`:
- board.rb         → Board representation
- pieces/          → One file per piece class (Pawn, Knight, Bishop, Rook, Queen, King)
- piece.rb         → Abstract/common piece logic
- actionable.rb    → Mixin encapsulating “can-act” behavior (Strategy pattern)
- validatable.rb   → Mixin for move-validation logic
- unpackable.rb    → Mixin for deserializing saved state
- rememberable.rb  → Mixin for serializing game state
- displayable.rb   → Mixin for console output/board rendering
- Tests mirror the lib structure under `spec/chess`

##### Key Architecture Insights from README
- Standard Ruby project scaffold generated by Thunder::Generator.
- No external services; all logic lives in-process.
- Intended to be extended by adding more features into `lib` and `spec`.

##### Main Components & Their Relationships
A. Components:
1. CLI Layer (bin/chess)
2. Game Engine Layer
– GameState
– Board
– Piece classes (Pawn, Knight, …)
3. Behavior Mixins
– Actionable, Validatable, Displayable, Rememberable, Unpackable
4. Persistence (file-based save/load via Rememberable/Unpackable)
5. Test Suite (RSpec)
B. Interactions:
- User invokes `bin/chess` → CLI parses commands → calls GameState
- GameState holds a Board instance with Piece objects
- Piece classes include mixins for movement rules (Validatable), action logic (Actionable)
- Displayable renders Board to console
- Rememberable serializes GameState to disk; Unpackable reverses
- Tests depend on all core classes to validate behavior
C. Architectural Patterns:
- Domain-driven design: clear separation of domain entities (GameState, Board, Piece)
- Mixin/Strategy patterns for behaviors (move validation, display, serialization)
- Single Responsibility: each file/module has one concern
D. Core Technologies:
- Ruby 2.x (Gemfile)
- RSpec for testing
- Standard library for file I/O (save/load)

##### Detailed Capture of Essential Architecture
- Mixin is represented and its role is annotated.
- Piece hierarchy (inheritance) from `Piece` superclass.
- Serialization boundary (in-memory vs. disk).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers Top to Bottom
    CLI("CLI Entry (bin/chess)"):::infra
    CLI -->|"invoke"| GameState

    GameState("GameState"):::domain
    GameState -->|"manages"| Board
    GameState -->|"holds pieces"| Piece
    GameState <-->|"serialize()/deserialize()"| Rememberable
    GameState <-->|"serialize()/deserialize()"| Unpackable

    Board("Board"):::domain
    Board -->|"renders"| Displayable
    Board -->|"contains"| Piece

    subgraph "Pieces"
        Piece["Piece (abstract)"]:::domain
        Pawn["Pawn"]:::domain
        Knight["Knight"]:::domain
        Bishop["Bishop"]:::domain
        Rook["Rook"]:::domain
        Queen["Queen"]:::domain
        King["King"]:::domain
        Piece -->|"inherits"| Pawn
        Piece -->|"inherits"| Knight
        Piece -->|"inherits"| Bishop
        Piece -->|"inherits"| Rook
        Piece -->|"inherits"| Queen
        Piece -->|"inherits"| King
        Pawn -->|"uses"| Actionable
        Pawn -->|"uses"| Validatable
        Knight -->|"uses"| Actionable
        Knight -->|"uses"| Validatable
        Bishop -->|"uses"| Actionable
        Bishop -->|"uses"| Validatable
        Rook -->|"uses"| Actionable
        Rook -->|"uses"| Validatable
        Queen -->|"uses"| Actionable
        Queen -->|"uses"| Validatable
        King -->|"uses"| Actionable
        King -->|"uses"| Validatable
    end

    subgraph "Mixins/Behaviors"
        Actionable("Actionable"):::mixin
        Validatable("Validatable"):::mixin
        Displayable("Displayable"):::mixin
        Rememberable("Rememberable"):::mixin
        Unpackable("Unpackable"):::mixin
    end

    subgraph "Test Suite"
        Tests("RSpec Tests (spec/)"):::test
    end

    %% Test dependencies
    Tests --> GameState
    Tests --> Board
    Tests --> Piece
    Tests --> Actionable
    Tests --> Validatable
    Tests --> Displayable
    Tests --> Rememberable
    Tests --> Unpackable

    %% Click Events
    click CLI "https://github.com/jaws-1684/chess/tree/main/bin/chess"
    click GameState "https://github.com/jaws-1684/chess/blob/main/lib/chess/gamestate/gamestate.rb"
    click Board "https://github.com/jaws-1684/chess/blob/main/lib/chess/board.rb"
    click Piece "https://github.com/jaws-1684/chess/blob/main/lib/chess/piece.rb"
    click Pawn "https://github.com/jaws-1684/chess/blob/main/lib/chess/pieces/pawn.rb"
    click Knight "https://github.com/jaws-1684/chess/blob/main/lib/chess/pieces/knight.rb"
    click Bishop "https://github.com/jaws-1684/chess/blob/main/lib/chess/pieces/bishop.rb"
    click Rook "https://github.com/jaws-1684/chess/blob/main/lib/chess/pieces/rook.rb"
    click Queen "https://github.com/jaws-1684/chess/blob/main/lib/chess/pieces/queen.rb"
    click King "https://github.com/jaws-1684/chess/blob/main/lib/chess/pieces/king.rb"
    click Actionable "https://github.com/jaws-1684/chess/blob/main/lib/chess/actionable.rb"
    click Validatable "https://github.com/jaws-1684/chess/blob/main/lib/chess/validatable.rb"
    click Displayable "https://github.com/jaws-1684/chess/blob/main/lib/chess/displayable.rb"
    click Rememberable "https://github.com/jaws-1684/chess/blob/main/lib/chess/rememberable.rb"
    click Unpackable "https://github.com/jaws-1684/chess/blob/main/lib/chess/unpackable.rb"
    click Tests "https://github.com/jaws-1684/chess/tree/main/spec/"

    %% Styles
    classDef domain fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef mixin fill:#DFFFD6,stroke:#228B22,color:#228B22;
    classDef infra fill:#FFF5BA,stroke:#d4a017,color:#d4a017;
    classDef test fill:#F4CCCC,stroke:#a80000,color:#a80000;
```
