# carlini/regex-chess architecture

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

- Interactive diagram: https://gitdiagram.com/carlini/regex-chess
- Repository: https://github.com/carlini/regex-chess

## Overview

##### Main Components
- Interactive Runner (main.py): Acts as the entry point. It loads the regex rules from regex-chess.json and enters the game loop where it applies regex substitutions to the current board state before accepting user moves.
- Regex Transformation Engine: Represented by the use of the regex-chess.json file along with Python’s re module (as seen directly in main.py). This is the core mechanism that “transforms” the board state.
- Chess Logic Engine (chess_engine.py): This likely contains routines that manage board state, validate moves (possibly integrating or being called from within minimax evaluations), and drive the game’s rules.
- Compiler/Instruction Components (compiler.py and instruction_set.py): These files suggest functionality to translate or interpret higher-level chess move instructions into the regex patterns used by the engine. They may be used to create or validate the regex definitions.
- JSON Utility (write_regex_json.py): This script probably handles generating or updating the regex transformation rules (the JSON file), making the engine configurable.
- Testing Modules (test_pgn.py and tests.py): These provide unit or integration tests for the engine, ensuring that both regex-based move generation and overall chess logic behave as expected.

##### Relationships and Interactions
- The interactive loop in main.py uses the regex-chess.json definitions to apply a series of regular expression substitutions on the board state. It then collects user input and prints the updated board.
- The chess_engine.py may be responsible for wrapping or integrating the minimax search algorithm, using the result of the regex transformations to evaluate potential moves.
- The compiler components (compiler.py and instruction_set.py) likely serve as a layer that converts chess instruction concepts into concrete regex patterns. They might be invoked during a pre-processing stage or when generating/updating regex-chess.json.
- Utility scripts (write_regex_json.py) and test modules ensure the correctness and maintainability of the transformation logic and board state.

##### Architectural Patterns and Design Principles
- Modularity: Even in a small project, components are separated by functionality (engine logic, regex transformation, compilation of instructions, and I/O handling).
- Data-Driven Configuration: The use of regex-chess.json as a central “rules engine” element allows one to modify move behavior without touching the codebase.
- Extensibility: With separate modules for instruction set definition and compiling regex rules, the design supports future enhancements or rule changes.

##### Relevant Technologies
- Python’s standard libraries (particularly re, json) are at the core.
- The use of regular expressions as the means for state transformation is the standout design idea.
- A 2-ply minimax search is implemented, so the engine has at least a rudimentary AI component.

##### Detail and Clarity
- Every component is clearly labeled with its corresponding file(s) and a short description of its role.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    U["User"]:::external

    %% Main Controller
    MC["Main Controller (main.py)"]:::controller

    %% Regex Transformation Engine
    RX["Regex Rules (regex-chess.json)"]:::regex

    %% Chess Logic Engine
    CE["Chess Logic Engine (chess_engine.py)"]:::chess

    %% Compiler and Instruction Set
    CP["Compiler (compiler.py)"]:::compiler
    IS["Instruction Set (instruction_set.py)"]:::compiler

    %% JSON Utility for Regex Rules
    JU["JSON Utility (write_regex_json.py)"]:::jsonutil

    %% Testing Suite
    TP["Test PGN (test_pgn.py)"]:::test
    TS["Tests (tests.py)"]:::test

    %% Relationships
    U -->|"user_input"| MC
    MC -->|"load_regex_rules"| RX
    RX -->|"apply_transformations"| CE
    MC -->|"minimax_evaluation"| CE

    CP -->|"generate_regex"| JU
    IS -->|"define_instructions"| JU
    JU -->|"update_regex"| RX
    CP -->|"compile_instructions"| RX
    IS -->|"compile_instructions"| RX

    %% Testing feedback arrows (verification)
    TP ---|"validate_chess_logic"| CE
    TS ---|"integration_tests"| MC

    %% Styles
    classDef controller fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef regex fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef chess fill:#99CCFF,stroke:#333,stroke-width:2px;
    classDef compiler fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef jsonutil fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef test fill:#D1B3FF,stroke:#333,stroke-width:2px;
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:2px;

    %% Click Events
    click MC "https://github.com/carlini/regex-chess/blob/main/main.py"
    click RX "https://github.com/carlini/regex-chess/blob/main/regex-chess.json"
    click CE "https://github.com/carlini/regex-chess/blob/main/chess_engine.py"
    click CP "https://github.com/carlini/regex-chess/blob/main/compiler.py"
    click IS "https://github.com/carlini/regex-chess/blob/main/instruction_set.py"
    click JU "https://github.com/carlini/regex-chess/blob/main/write_regex_json.py"
    click TP "https://github.com/carlini/regex-chess/blob/main/test_pgn.py"
    click TS "https://github.com/carlini/regex-chess/blob/main/tests.py"
```
