# nonamerose/automated-chess-player architecture

> Architecture diagram of the GitHub repository nonamerose/automated-chess-player, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nonamerose/automated-chess-player
- Repository: https://github.com/nonamerose/automated-chess-player

## Overview

1. **Overall shape**
   - This repo is split into two deployable parts: a **Java/Spring Boot backend** in `chessEngine/` and a **TypeScript/React frontend** in `front-end/`.
   - The architecture is a classic **client + service** setup: the frontend presents the game UI, while the backend owns chess rules and move selection.

2. **Backend boundary**
   - `com.example.chessEngine.ChessEngineApplication` is the Spring Boot entry point.
   - `AgentController` is the main exposed boundary on the server side, so the browser likely talks to the backend through HTTP endpoints here.
   - `application.properties` is the main runtime config surface; no database or queue infrastructure is visible.

3. **Core game engine**
   - The `ChessLogic` package is the heart of the system.
   - `Board` represents the current game state.
   - `BoardInitializer` sets up the starting position.
   - `Piece` is the shared abstraction for chess pieces, with concrete implementations for `Pawn`, `Rook`, `Knight`, `Bishop`, `Queen`, and `King`.

4. **Rules and move semantics**
   - Each piece class likely encapsulates legal-move logic for that piece type.
   - `PieceRepresentation` suggests a separate model for serializing or displaying pieces, which is useful at the API/UI boundary so the frontend does not need engine internals.

5. **Agent subsystem**
   - The `Agent` package defines how moves are produced.
   - `Agent` is the common contract, `HumanAgent` represents user-driven play, and `RandomAgent` provides an automated opponent or test player.
   - `AgentName` is probably used to select which agent implementation to use through the API.

6. **End-to-end data flow**
   - The likely flow is: **frontend action → controller request → agent decides move → board updates through chess logic → updated board state returns to frontend**.
   - The backend appears to be stateful at the game/board level, but the visible code suggests state is kept in memory rather than persisted externally.

7. **Frontend role**
   - The frontend is a Vite-based React app, with `main.tsx` bootstrapping the app and `App.tsx` as the top-level UI.
   - `index.css` provides shared styling.
   - This repo tree does not show a large component hierarchy, so the UI may be relatively compact or still evolving.

8. **Frontend-backend integration**
   - The frontend is likely responsible for rendering the board, sending player actions, and displaying engine responses.
   - The backend is responsible for rules enforcement, turn handling, and AI/random move generation.
   - This keeps chess correctness centralized in the Java service rather than duplicated in the browser.

9. **Testing**
   - Backend tests live under `chessEngine/src/test/java`.
   - `ChessEngineApplicationTests` is the standard Spring Boot smoke test.
   - `Testing/Game.java` looks like a custom test harness or scenario driver for chess behavior, separate from the Spring application test.

10. **Build and tooling**
   - Backend: Maven-based Java project with the Maven wrapper (`mvnw`, `pom.xml`).
   - Frontend: Node/Vite toolchain with TypeScript, ESLint, and Vite config.
   - The repo does not show Docker, CI, or deployment manifests, so the architecture is primarily source-level rather than infrastructure-defined.

11. **Important architectural boundary**
   - The key design boundary is between **presentation** and **game engine**.
   - The frontend should be treated as a thin client.
   - The chess rules, board state transitions, and agent behavior are concentrated in the backend domain packages.

12. **What is not present**
   - No persistence layer, cache, auth, or external services are visible in the tree.
   - That implies the system is focused on a single-session chess experience rather than a multi-user platform with stored games.

Main entry points: [`chessEngine/src/main/java/com/example/chessEngine/controller/AgentController.java`](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/com/example/chessEngine/controller/AgentController.java) (Agent API), [`chessEngine/src/main/java/ChessLogic/Board.java`](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/Board.java) (Board), [`chessEngine/src/main/java/Agent/Agent.java`](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/Agent/Agent.java) (Agent), [`chessEngine/src/main/java/ChessLogic/Piece.java`](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/Piece.java) (Piece)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_be_boot["Boot app<br/>Spring Boot entry"]
  node_be_controller["Agent API<br/>HTTP controller"]
  node_be_config["Config"]
  node_agent_contract["Agent<br/>[Agent.java]"]
  node_agent_human["Human<br/>manual agent<br/>[HumanAgent.java]"]
  node_agent_random["Random<br/>automated agent<br/>[RandomAgent.java]"]
  node_agent_name["Agent name<br/>selection enum<br/>[AgentName.java]"]
  node_board[("Board<br/>game state<br/>[Board.java]")]
  node_initializer["Setup<br/>board initializer"]
  node_piece_base["Piece<br/>[Piece.java]"]
  node_piece_repr["Representation<br/>DTO/model"]
  node_piece_moves["Piece rules<br/>piece implementations"]
  node_backend_tests["Tests<br/>test harness"]
end

subgraph group_frontend["Frontend"]
  node_fe_main["Main<br/>React entry<br/>[main.tsx]"]
  node_fe_app["App<br/>UI shell<br/>[App.tsx]"]
  node_fe_styles["Styles<br/>global CSS<br/>[index.css]"]
end

node_fe_main -->|"mounts"| node_fe_app
node_fe_app -->|"uses"| node_fe_styles
node_fe_app -->|"calls"| node_be_controller
node_be_boot -->|"exposes"| node_be_controller
node_be_controller -->|"uses"| node_agent_contract
node_be_controller -->|"updates"| node_board
node_agent_contract -.->|"implemented by"| node_agent_human
node_agent_contract -.->|"implemented by"| node_agent_random
node_agent_name -->|"selects"| node_agent_contract
node_initializer -->|"creates"| node_board
node_board -->|"contains"| node_piece_base
node_piece_base -.->|"specialized by"| node_piece_moves
node_piece_moves -->|"validates"| node_board
node_piece_base -->|"mapped to"| node_piece_repr
node_be_controller -->|"returns"| node_piece_repr
node_backend_tests -.->|"checks"| node_be_boot
node_backend_tests -.->|"exercises"| node_board

click node_fe_main "https://github.com/nonamerose/automated-chess-player/blob/main/front-end/src/main.tsx"
click node_fe_app "https://github.com/nonamerose/automated-chess-player/blob/main/front-end/src/App.tsx"
click node_fe_styles "https://github.com/nonamerose/automated-chess-player/blob/main/front-end/src/index.css"
click node_be_boot "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/com/example/chessEngine/ChessEngineApplication.java"
click node_be_controller "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/com/example/chessEngine/controller/AgentController.java"
click node_be_config "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/resources/application.properties"
click node_agent_contract "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/Agent/Agent.java"
click node_agent_human "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/Agent/HumanAgent.java"
click node_agent_random "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/Agent/RandomAgent.java"
click node_agent_name "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/Agent/AgentName.java"
click node_board "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/Board.java"
click node_initializer "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/BoardInitializer.java"
click node_piece_base "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/Piece.java"
click node_piece_repr "https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/PieceRepresentation.java"
click node_backend_tests "https://github.com/nonamerose/automated-chess-player/tree/main/chessEngine/src/test/java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_be_boot,node_be_controller,node_be_config,node_agent_contract,node_agent_human,node_agent_random,node_agent_name,node_board,node_initializer,node_piece_base,node_piece_repr,node_piece_moves,node_backend_tests toneBlue
class node_fe_main,node_fe_app,node_fe_styles toneAmber
```

## Components

### Backend

Spring Boot service with chess rules and move selection

- [Boot app](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/com/example/chessEngine/ChessEngineApplication.java): Spring Boot entry · Starts the backend application · `chessEngine/src/main/java/com/example/chessEngine/ChessEngineApplication.java`
- [Agent API](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/com/example/chessEngine/controller/AgentController.java): HTTP controller · Main server boundary for browser requests and agent actions · `chessEngine/src/main/java/com/example/chessEngine/controller/AgentController.java`
- [Config](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/resources/application.properties): runtime config · Application properties and server configuration · `chessEngine/src/main/resources/application.properties`
- [Agent](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/Agent/Agent.java): agent contract · Common interface for move-producing strategies · `chessEngine/src/main/java/Agent/Agent.java`
- [Human](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/Agent/HumanAgent.java): manual agent · Represents user-driven play · `chessEngine/src/main/java/Agent/HumanAgent.java`
- [Random](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/Agent/RandomAgent.java): automated agent · Produces random moves for an opponent or test player · `chessEngine/src/main/java/Agent/RandomAgent.java`
- [Agent name](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/Agent/AgentName.java): selection enum · Identifies which agent implementation to use · `chessEngine/src/main/java/Agent/AgentName.java`
- [Board](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/Board.java): game state · Current chess position and state transitions · `chessEngine/src/main/java/ChessLogic/Board.java`
- [Setup](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/BoardInitializer.java): board initializer · Creates the starting board position · `chessEngine/src/main/java/ChessLogic/BoardInitializer.java`
- [Piece](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/Piece.java): piece abstraction · Shared model and behavior for chess pieces · `chessEngine/src/main/java/ChessLogic/Piece.java`
- [Representation](https://github.com/nonamerose/automated-chess-player/blob/main/chessEngine/src/main/java/ChessLogic/PieceRepresentation.java): DTO/model · Serialized or display-friendly piece representation · `chessEngine/src/main/java/ChessLogic/PieceRepresentation.java`
- **Piece rules**: piece implementations · Concrete movement logic for chess pieces
- [Tests](https://github.com/nonamerose/automated-chess-player/tree/main/chessEngine/src/test/java): test harness · Backend smoke tests and chess scenario driver · `chessEngine/src/test/java`

### Frontend

Vite React client for the game UI

- [Main](https://github.com/nonamerose/automated-chess-player/blob/main/front-end/src/main.tsx): React entry · Bootstraps the frontend application · `front-end/src/main.tsx`
- [App](https://github.com/nonamerose/automated-chess-player/blob/main/front-end/src/App.tsx): UI shell · Top-level user interface for the chess experience · `front-end/src/App.tsx`
- [Styles](https://github.com/nonamerose/automated-chess-player/blob/main/front-end/src/index.css): global CSS · Shared application styling · `front-end/src/index.css`

## Connections

- Main → App: mounts · Frontend entry renders the application shell
- App → Styles: uses · Application UI relies on shared styling
- App → Agent API: calls · UI sends game actions to the backend API
- Boot app → Agent API: exposes · Spring Boot application hosts the controller endpoints
- Agent API → Agent: uses · Controller delegates move generation through the agent abstraction
- Agent API → Board: updates · Requests lead to board state changes
- Agent → Human: implemented by · Human agent provides manual play behavior
- Agent → Random: implemented by · Random agent provides automated play behavior
- Agent name → Agent: selects · Agent selection resolves to an agent implementation
- Setup → Board: creates · Initial setup populates the starting position
- Board → Piece: contains · Board stores and manipulates pieces
- Piece → Piece rules: specialized by · Concrete piece classes define legal move behavior
- Piece rules → Board: validates · Piece movement logic depends on board state
- Piece → Representation: mapped to · Engine pieces can be converted to a serializable representation
- Agent API → Representation: returns · API responses likely expose board and piece data through representations
- Tests → Boot app: checks · Spring smoke tests cover application startup
- Tests → Board: exercises · Custom test harness targets chess behavior