# datavorous/touchgrass architecture

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

- Interactive diagram: https://gitdiagram.com/datavorous/touchgrass
- Repository: https://github.com/datavorous/touchgrass

## Overview

##### Project type and purpose
- This is a standalone, backend-only chess engine (named “touchgrass”) implemented in Python.
- Its primary purpose is to encapsulate chess logic: board representation, piece definitions, move generation, and game flow.
- It exposes an API surface for external callers (cli, GUI, or other tools) via `api.py` and a command-line entry point in `main.py`.

##### File structure
- Top-level files:
- `.gitignore` – VCS ignore rules
- `README.md` – project description
- `api.py` – external interface/facade
- `main.py` – CLI entry point
- `utils.py` – shared helpers (e.g., logging, configuration)
- `backend/` directory (core logic):
- `board.py` – board representation (squares, piece placement)
- `pieces.py` – piece definitions, movement rules
- `move_gen.py` – move-generation engine, legal move computation
- `game.py` – game state management, turn order, rules enforcement
- There are no frontend clients or databases—this is a pure in-memory engine.

##### README for additional insights
- The README confirms “tiny chess engine” and “only backend implemented.”

a. Main components:
- Core Modules (in-memory chess logic):
– Board Module (`board.py`)
– Pieces Module (`pieces.py`)
– Move Generation Module (`move_gen.py`)
– Game Controller Module (`game.py`)
- Utility Layer (`utils.py`)
- API Layer (`api.py`)
- CLI Entry Point (`main.py`)
- External Consumer (e.g., GUI, CLI user, test harness)
b. Relationships and interactions:
- `main.py` imports `api.py` and `utils.py` to initialize the engine, parse CLI arguments or commands.
- `api.py` exposes functions like `initialize_game()`, `get_legal_moves()`, `make_move()`, internally calling `game.py`, `move_gen.py`, and `board.py`.
- `game.py` maintains state, uses `board.py` to track positions and `move_gen.py` for legal-moves logic.
- `move_gen.py` relies on `pieces.py` for piece‐specific move rules and `board.py` for occupancy checks.
- `utils.py` is used across all layers for logging, configuration, or shared helper routines.
c. Architectural patterns and principles:
- Layered architecture: clear separation between core logic, API facade, and entry point.
- Single Responsibility: each module has a well-defined role.
- Inversion of Control at the API boundary: external callers drive the engine through a limited interface.
d. Key technologies:
- Python 3.x as the implementation language.
- Standard library modules only (no external dependencies shown).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    External["External Consumer"]:::entry

    %% Entry Point Layer
    Main["main.py"]:::entry
    External -->|"CLI invoke"| Main
    External -->|"Programmatic call"| Api

    %% API Layer
    subgraph "API Layer"
        Api["api.py"]:::api
    end
    Main -->|"uses"| Api

    %% Utility Layer
    Utils["utils.py"]:::utils

    %% Core Logic Layer
    subgraph "Core Logic"
        Board["board.py"]:::coreLogic
        Pieces["pieces.py"]:::coreLogic
        MoveGen["move_gen.py"]:::coreLogic
        Game["game.py"]:::coreLogic
    end

    %% Interactions
    Main -->|"uses"| Utils
    Api -->|"initialize_game()"| Game
    Api -->|"get_legal_moves()"| MoveGen
    Api -->|"make_move() / update state"| Game
    Api -->|"logging/config"| Utils

    Game -->|"state management"| Board
    Game -->|"compute legal moves"| MoveGen
    MoveGen -->|"piece rules"| Pieces
    MoveGen -->|"occupancy checks"| Board

    Board -->|"helpers"| Utils
    Pieces -->|"helpers"| Utils
    MoveGen -->|"helpers"| Utils
    Game -->|"helpers"| Utils

    %% Click Events
    click Board "https://github.com/datavorous/touchgrass/blob/main/backend/board.py"
    click Pieces "https://github.com/datavorous/touchgrass/blob/main/backend/pieces.py"
    click MoveGen "https://github.com/datavorous/touchgrass/blob/main/backend/move_gen.py"
    click Game "https://github.com/datavorous/touchgrass/blob/main/backend/game.py"
    click Utils "https://github.com/datavorous/touchgrass/blob/main/utils.py"
    click Api "https://github.com/datavorous/touchgrass/blob/main/api.py"
    click Main "https://github.com/datavorous/touchgrass/blob/main/main.py"

    %% Styles
    classDef coreLogic fill:#add8e6,stroke:#333,stroke-width:1px
    classDef api fill:#90ee90,stroke:#333,stroke-width:1px
    classDef entry fill:#ffa500,stroke:#333,stroke-width:1px
    classDef utils fill:#d3d3d3,stroke:#333,stroke-width:1px
```
