# zoecyber001/ghost-shell architecture

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

- Interactive diagram: https://gitdiagram.com/zoecyber001/ghost-shell
- Repository: https://github.com/zoecyber001/ghost-shell
- Video tour (about a minute): https://gitdiagram.com/zoecyber001/ghost-shell/video

## Overview

Ghost-Shell is a desktop chess-playing bot: the user chooses a side and supplies opponent moves, while the app detects the board, selects a move with Stockfish, previews it, and clicks it into the chess UI. `main.py` coordinates the game loop and chess position; vision, engine, humanizer, and overlay provide distinct runtime stages. Source excerpts show these direct calls; the README documents the HUD and humanized interaction, and the tree does not include an `assets` directory, so the Stockfish executable is represented as an external dependency.

Main entry points: [`main.py`](https://github.com/zoecyber001/ghost-shell/blob/master/main.py) (Game loop), [`core/engine.py`](https://github.com/zoecyber001/ghost-shell/blob/master/core/engine.py) (Move engine), [`core/humanizer.py`](https://github.com/zoecyber001/ghost-shell/blob/master/core/humanizer.py) (Humanized input), [`core/vision.py`](https://github.com/zoecyber001/ghost-shell/blob/master/core/vision.py) (Board vision)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Game orchestration"]
  node_main["Game loop<br/>[main.py]"]
  node_position["Chess position<br/>[main.py]"]
end

subgraph group_perception["Board perception"]
  node_vision["Board vision<br/>[vision.py]"]
end

subgraph group_decision["Move decision"]
  node_engine["Move engine<br/>[engine.py]"]
end

subgraph group_interaction["Screen interaction"]
  node_humanizer["Humanized input<br/>[humanizer.py]"]
  node_overlay["Move HUD<br/>[overlay.py]"]
end

subgraph group_support["Runtime support"]
  node_config["Configuration<br/>[config.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

node_user(("Player"))
node_screen["Desktop screen"]
node_stockfish["Stockfish"]
node_mouse["Desktop mouse"]

node_user -->|"chooses side, enters moves"| node_main
node_main -->|"finds board, detects side"| node_vision
node_vision -->|"captures screen"| node_screen
node_main -->|"waits for changes"| node_vision
node_main -->|"updates position"| node_position
node_main -->|"requests move"| node_engine
node_engine -->|"queries candidate moves"| node_stockfish
node_main -->|"previews move"| node_overlay
node_main -->|"executes move"| node_humanizer
node_humanizer -->|"moves and clicks"| node_mouse
node_main -->|"reads settings"| node_config
node_engine -->|"reads settings"| node_config
node_humanizer -->|"reads settings"| node_config
node_main -->|"logs game events"| node_logger
node_vision -->|"logs detection"| node_logger
node_engine -->|"logs engine events"| node_logger
node_humanizer -->|"logs actions"| node_logger

click node_main "https://github.com/zoecyber001/ghost-shell/blob/master/main.py"
click node_position "https://github.com/zoecyber001/ghost-shell/blob/master/main.py"
click node_vision "https://github.com/zoecyber001/ghost-shell/blob/master/core/vision.py"
click node_engine "https://github.com/zoecyber001/ghost-shell/blob/master/core/engine.py"
click node_humanizer "https://github.com/zoecyber001/ghost-shell/blob/master/core/humanizer.py"
click node_overlay "https://github.com/zoecyber001/ghost-shell/blob/master/ui/overlay.py"
click node_config "https://github.com/zoecyber001/ghost-shell/blob/master/utils/config.py"
click node_logger "https://github.com/zoecyber001/ghost-shell/blob/master/utils/logger.py"

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_main,node_position,node_screen toneBlue
class node_vision toneAmber
class node_engine toneMint
class node_humanizer,node_overlay toneRose
class node_config,node_logger,node_user,node_stockfish,node_mouse toneIndigo
```

## Components

### Game orchestration

- [Game loop](https://github.com/zoecyber001/ghost-shell/blob/master/main.py): `main.py`
- [Chess position](https://github.com/zoecyber001/ghost-shell/blob/master/main.py): `main.py`

### Board perception

- [Board vision](https://github.com/zoecyber001/ghost-shell/blob/master/core/vision.py): `core/vision.py`

### Move decision

- [Move engine](https://github.com/zoecyber001/ghost-shell/blob/master/core/engine.py): `core/engine.py`

### Screen interaction

- [Humanized input](https://github.com/zoecyber001/ghost-shell/blob/master/core/humanizer.py): `core/humanizer.py`
- [Move HUD](https://github.com/zoecyber001/ghost-shell/blob/master/ui/overlay.py): `ui/overlay.py`

### Runtime support

- [Configuration](https://github.com/zoecyber001/ghost-shell/blob/master/utils/config.py): `utils/config.py`
- [Logging](https://github.com/zoecyber001/ghost-shell/blob/master/utils/logger.py): `utils/logger.py`

### Other components

- **Player**
- **Desktop screen**
- **Stockfish**
- **Desktop mouse**

## Connections

- Player → Game loop: chooses side, enters moves
- Game loop → Board vision: finds board, detects side
- Board vision → Desktop screen: captures screen
- Game loop → Board vision: waits for changes
- Game loop → Chess position: updates position
- Game loop → Move engine: requests move
- Move engine → Stockfish: queries candidate moves
- Game loop → Move HUD: previews move
- Game loop → Humanized input: executes move
- Humanized input → Desktop mouse: moves and clicks
- Game loop → Configuration: reads settings
- Move engine → Configuration: reads settings
- Humanized input → Configuration: reads settings
- Game loop → Logging: logs game events
- Board vision → Logging: logs detection
- Move engine → Logging: logs engine events
- Humanized input → Logging: logs actions