# haxdds/fischer architecture

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

- Interactive diagram: https://gitdiagram.com/haxdds/fischer
- Repository: https://github.com/haxdds/fischer

## Overview

##### Project type and purpose
- This is a standalone Java desktop application that implements the game of chess.
- It follows the Model-View-Controller (MVC) design pattern and uses a simple brute-force engine with plans for machine-learning extensions.
- The GUI is Swing/Java-based and drives the game loop, while the “engine” component evaluates board positions to suggest or play moves.

##### File structure
- Top-level:
- src/main/chess – contains all Java code, sub-divided by package:
– controller – input listeners, move generation, validation, translation.
– engine – search tree (Node), evaluator, Engine orchestrator.
– game – high-level Game loop, Player abstraction, Clock.
– gui – BoardGUI, overall GUI.
- res/chess/pieces – image assets for pieces.
- test/main – JUnit tests for controller and structure.
- Build/deploy: Makefile for bash, javac/java commands in README.
- Configuration: .gitignore, GitHub issue templates, CONTRIBUTING, LICENSE.

##### Additional README insights
- Explicit mention of MVC and the Factory pattern.
- Current and planned features: castling, en-passant, pawn promotion, online play, ML engine.

##### Main components & their relationships
a. Components
- View (GUI) – renders Board, captures user clicks.
- Controller – Listener, MoveGenerator, MoveValidator, PositionValidator, TranslationSignature, MoveHandler.
- Model (Structure) – Board state, PieceSet, Piece, Move, Square, Group, factories.
- Game Manager – Game, Player, Clock, MoveLog.
- Engine – Engine entry point, Evaluator, Node (search tree).
- Resources – piece images.
- Tests – unit tests for core logic.
b. Interactions
- GUI forwards user actions to Controller.Listener.
- Controller uses TranslationSignature to map clicks → Move objects.
- MoveGenerator proposes moves; Validator checks legality against Model.Board.
- MoveHandler updates Model.Board via BoardHandler/ChessGroupFactory.
- Game updates Player turns, logs moves, updates Clock, then calls Engine for AI moves.
- Engine queries Model.Board, builds Node tree, uses Evaluator to score, returns best Move.
- GUI observes Model changes (pull-or-push) and re-renders board with Resource images.
c. Architectural patterns
- MVC: clear separation of GUI (View), Controller logic, and Domain Model.
- Factory: ChessGroupFactory to instantiate piece groups.
- Single Responsibility: each class has focused functionality (e.g., MoveValidator only checks rules).
d. Key technologies
- Java SE, Swing (or similar) for GUI
- JUnit for tests
- Makefile for build scripting
- GitHub templates for collaboration

##### Detailed capture of essential elements
- BoardHandler/ChessGroupFactory to show where pieces get instantiated or updated.
- Game loop controlling turn order and invoking Engine for AI.
- Resource folder as “assets” tied to View for piece rendering.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Application Entry"
        Main["Main"]:::service
    end

    subgraph "View (GUI)"
        GUI["GUI"]:::view
        BoardGUI["BoardGUI"]:::view
        Assets["Assets (piece images)"]:::view
    end

    subgraph "Controller"
        Listener["Listener"]:::controller
        TransSig["TranslationSignature"]:::controller
        MoveGen["MoveGenerator"]:::controller
        MoveVal["MoveValidator"]:::controller
        PosVal["PositionValidator"]:::controller
        MoveHandler["MoveHandler"]:::controller
    end

    subgraph "Model (Structure)"
        Board["Board"]:::model
        BoardHandler["BoardHandler"]:::model
        ChessGroupFactory["ChessGroupFactory"]:::model
        ChessGroupFactoryImpl["ChessGroupFactoryImpl"]:::model
        Group["Group"]:::model
        Piece["Piece"]:::model
        PieceSet["PieceSet"]:::model
        MoveModel["Move"]:::model
        Square["Square"]:::model
        Color["Color"]:::model
        Type["Type"]:::model
        MoveLog["MoveLog"]:::model
        TranslationModel["Translation"]:::model
    end

    subgraph "Game & Engine Services"
        Game["Game"]:::service
        Player["Player"]:::service
        Clock["Clock"]:::service
        EngineServ["Engine"]:::service
        Evaluator["Evaluator"]:::service
        NodeServ["Node"]:::service
    end

    Main --> GUI
    GUI --> BoardGUI
    BoardGUI --> Listener
    Listener --> TransSig
    Listener --> MoveGen
    TransSig --> TranslationModel
    MoveGen -->|"generateMoves(Board)"| Board
    MoveGen -->|proposeMoves| MoveModel
    Listener --> MoveVal
    Listener --> PosVal
    MoveVal -->|"validate(Move)"| MoveModel
    MoveVal --> Board
    MoveHandler --> BoardHandler
    MoveHandler --> ChessGroupFactory
    MoveHandler --> Board
    Listener --> MoveHandler
    Game --> Player
    Game --> Clock
    Game --> MoveHandler
    Game -->|"invokeEngine"| EngineServ
    EngineServ -->|"buildNodeTree(Board)"| Board
    EngineServ --> NodeServ
    EngineServ --> Evaluator
    Evaluator --> NodeServ
    EngineServ --> MoveModel
    Board -->|"observedBy"| GUI

    Assets --> GUI

    click BoardGUI "https://github.com/haxdds/fischer/blob/master/src/main/chess/gui/BoardGUI.java"
    click GUI "https://github.com/haxdds/fischer/blob/master/src/main/chess/gui/GUI.java"
    click Listener "https://github.com/haxdds/fischer/blob/master/src/main/chess/controller/Listener.java"
    click TransSig "https://github.com/haxdds/fischer/blob/master/src/main/chess/controller/TranslationSignature.java"
    click MoveGen "https://github.com/haxdds/fischer/blob/master/src/main/chess/controller/MoveGenerator.java"
    click MoveVal "https://github.com/haxdds/fischer/blob/master/src/main/chess/controller/MoveValidator.java"
    click PosVal "https://github.com/haxdds/fischer/blob/master/src/main/chess/controller/PositionValidator.java"
    click MoveHandler "https://github.com/haxdds/fischer/blob/master/src/main/chess/controller/MoveHandler.java"
    click Board "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/Board.java"
    click BoardHandler "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/BoardHandler.java"
    click ChessGroupFactory "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/ChessGroupFactory.java"
    click ChessGroupFactoryImpl "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/ChessGroupFactoryImpl.java"
    click Group "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/Group.java"
    click Piece "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/Piece.java"
    click PieceSet "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/PieceSet.java"
    click MoveModel "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/Move.java"
    click Square "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/Square.java"
    click Color "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/Color.java"
    click Type "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/Type.java"
    click MoveLog "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/MoveLog.java"
    click TranslationModel "https://github.com/haxdds/fischer/blob/master/src/main/chess/structure/Translation.java"
    click Game "https://github.com/haxdds/fischer/blob/master/src/main/chess/game/Game.java"
    click Player "https://github.com/haxdds/fischer/blob/master/src/main/chess/game/Player.java"
    click Clock "https://github.com/haxdds/fischer/blob/master/src/main/chess/game/Clock.java"
    click EngineServ "https://github.com/haxdds/fischer/blob/master/src/main/chess/engine/Engine.java"
    click Evaluator "https://github.com/haxdds/fischer/blob/master/src/main/chess/engine/Evaluator.java"
    click NodeServ "https://github.com/haxdds/fischer/blob/master/src/main/chess/engine/Node.java"
    click Main "https://github.com/haxdds/fischer/blob/master/src/main/chess/Main.java"

    classDef view fill:#B3DFFF,stroke:#333,stroke-width:1px
    classDef controller fill:#C2F0C2,stroke:#333,stroke-width:1px
    classDef model fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef service fill:#E0B3FF,stroke:#333,stroke-width:1px
```
