# ethanchenhyland/funchessengine architecture

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

- Interactive diagram: https://gitdiagram.com/ethanchenhyland/funchessengine
- Repository: https://github.com/ethanchenhyland/funchessengine

## Overview

FunChessEngine combines a standalone chess engine with a local Engine Lab for play, analysis, game-library management, and training. The main user workflow is to play or import a game, review positions with engine analysis, and save or organize games and study data locally. The README also documents tournament and benchmark tools, opening exploration, and an editable repertoire. The graph includes these major capabilities; unsampled implementation details are represented only where the tree or documentation supports them.

Main entry points: [`gui/server.py`](https://github.com/ethanchenhyland/funchessengine/blob/main/gui/server.py) (Local API), [`desktop/main.js`](https://github.com/ethanchenhyland/funchessengine/blob/main/desktop/main.js) (Electron Shell), [`agent.py`](https://github.com/ethanchenhyland/funchessengine/blob/main/agent.py) (Move Search), [`uci.py`](https://github.com/ethanchenhyland/funchessengine/blob/main/uci.py) (UCI Protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Chess Engine"]
  node_engine_api["Move Search<br/>[agent.py]"]
  node_uci["UCI Protocol<br/>[uci.py]"]
end

subgraph group_workstation["Local Workstation"]
  node_gui_server["Local API<br/>[server.py]"]
  node_gui_jobs["Background Jobs<br/>[jobs.py]"]
  node_gui_workspace["Session Workspace<br/>[workspace.py]"]
  node_workbench_ui["Engine Lab UI<br/>[workbench.js]"]
  node_game_ui["Game And Review UI<br/>[app.js]"]
  node_workflow_ui["Workflow UI<br/>[workflows.js]"]
end

subgraph group_library["Games And Studies"]
  node_database_ui["Library Browser"]
  node_explorer_ui["Opening Explorer"]
  node_game_store[("Game Database<br/>[store.py]")]
  node_catalog["Game Catalog<br/>[catalog.py]"]
  node_library_workbench["Library Operations<br/>[workbench.py]"]
  node_opening_book[("Opening Repertoire<br/>[store.py]")]
  node_reporting["Game Reports<br/>[generator.py]"]
end

subgraph group_tools["Analysis Tools"]
  node_arena["Tournament Runner<br/>[tournament.py]"]
  node_uci_client["External Engine Client<br/>[uci_client.py]"]
  node_harness["Match And Benchmark Tools<br/>[arena.py]"]
end

subgraph group_desktop["Desktop Shell"]
  node_desktop_shell["Electron Shell<br/>[main.js]"]
  node_desktop_storage[("Desktop Metadata Store<br/>[storage.js]")]
end

node_user(("Local User"))
node_external_uci(("Installed UCI Engine"))

node_user -->|"uses"| node_workbench_ui
node_workbench_ui -->|"requests"| node_gui_server
node_gui_server -->|"searches positions"| node_engine_api
node_gui_server -->|"dispatches jobs"| node_gui_jobs
node_gui_server -->|"manages sessions"| node_gui_workspace
node_user -->|"plays and reviews"| node_game_ui
node_game_ui -->|"requests"| node_gui_server
node_gui_server -->|"reads and writes"| node_game_store
node_gui_server -->|"handles library actions"| node_library_workbench
node_library_workbench -->|"queries catalog"| node_catalog
node_catalog -->|"reads games"| node_game_store
node_user -->|"browses games"| node_database_ui
node_database_ui -->|"requests library data"| node_gui_server
node_user -->|"explores openings"| node_explorer_ui
node_explorer_ui -->|"requests continuations"| node_gui_server
node_gui_server -->|"manages repertoire"| node_opening_book
node_gui_server -->|"generates reports"| node_reporting
node_workflow_ui -->|"requests workflows"| node_gui_server
node_gui_server -->|"serves engine protocol"| node_uci
node_uci -->|"requests moves"| node_engine_api
node_gui_server -->|"runs tournaments"| node_arena
node_arena -->|"compares engines"| node_uci_client
node_uci_client -.->|"speaks UCI"| node_external_uci
node_harness -->|"evaluates matches"| node_engine_api
node_user -->|"launches workstation"| node_desktop_shell
node_desktop_shell -->|"starts backend"| node_gui_server
node_desktop_shell -->|"persists metadata"| node_desktop_storage

click node_engine_api "https://github.com/ethanchenhyland/funchessengine/blob/main/agent.py"
click node_uci "https://github.com/ethanchenhyland/funchessengine/blob/main/uci.py"
click node_gui_server "https://github.com/ethanchenhyland/funchessengine/blob/main/gui/server.py"
click node_gui_jobs "https://github.com/ethanchenhyland/funchessengine/blob/main/gui/jobs.py"
click node_gui_workspace "https://github.com/ethanchenhyland/funchessengine/blob/main/gui/workspace.py"
click node_workbench_ui "https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/workbench.js"
click node_game_ui "https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/app.js"
click node_workflow_ui "https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/workflows.js"
click node_database_ui "https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/database-productivity.js"
click node_explorer_ui "https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/database-explorer.js"
click node_game_store "https://github.com/ethanchenhyland/funchessengine/blob/main/librarydb/store.py"
click node_catalog "https://github.com/ethanchenhyland/funchessengine/blob/main/librarydb/catalog.py"
click node_library_workbench "https://github.com/ethanchenhyland/funchessengine/blob/main/librarydb/workbench.py"
click node_opening_book "https://github.com/ethanchenhyland/funchessengine/blob/main/openingbook/store.py"
click node_reporting "https://github.com/ethanchenhyland/funchessengine/blob/main/reporting/generator.py"
click node_arena "https://github.com/ethanchenhyland/funchessengine/blob/main/integrations/tournament.py"
click node_uci_client "https://github.com/ethanchenhyland/funchessengine/blob/main/integrations/uci_client.py"
click node_harness "https://github.com/ethanchenhyland/funchessengine/blob/main/harness/arena.py"
click node_desktop_shell "https://github.com/ethanchenhyland/funchessengine/blob/main/desktop/main.js"
click node_desktop_storage "https://github.com/ethanchenhyland/funchessengine/blob/main/desktop/storage.js"

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_engine_api,node_uci,node_user toneBlue
class node_gui_server,node_gui_jobs,node_gui_workspace,node_workbench_ui,node_game_ui,node_workflow_ui toneAmber
class node_database_ui,node_explorer_ui,node_game_store,node_catalog,node_library_workbench,node_opening_book,node_reporting toneMint
class node_arena,node_uci_client,node_harness toneRose
class node_desktop_shell,node_desktop_storage,node_external_uci toneIndigo
```

## Components

### Chess Engine

- [Move Search](https://github.com/ethanchenhyland/funchessengine/blob/main/agent.py): `agent.py`
- [UCI Protocol](https://github.com/ethanchenhyland/funchessengine/blob/main/uci.py): `uci.py`

### Local Workstation

- [Local API](https://github.com/ethanchenhyland/funchessengine/blob/main/gui/server.py): `gui/server.py`
- [Background Jobs](https://github.com/ethanchenhyland/funchessengine/blob/main/gui/jobs.py): `gui/jobs.py`
- [Session Workspace](https://github.com/ethanchenhyland/funchessengine/blob/main/gui/workspace.py): `gui/workspace.py`
- [Engine Lab UI](https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/workbench.js): `gui/static/workbench.js`
- [Game And Review UI](https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/app.js): `gui/static/app.js`
- [Workflow UI](https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/workflows.js): `gui/static/workflows.js`

### Games And Studies

- [Library Browser](https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/database-productivity.js): `gui/static/database-productivity.js`
- [Opening Explorer](https://github.com/ethanchenhyland/funchessengine/blob/main/gui/static/database-explorer.js): `gui/static/database-explorer.js`
- [Game Database](https://github.com/ethanchenhyland/funchessengine/blob/main/librarydb/store.py): `librarydb/store.py`
- [Game Catalog](https://github.com/ethanchenhyland/funchessengine/blob/main/librarydb/catalog.py): `librarydb/catalog.py`
- [Library Operations](https://github.com/ethanchenhyland/funchessengine/blob/main/librarydb/workbench.py): `librarydb/workbench.py`
- [Opening Repertoire](https://github.com/ethanchenhyland/funchessengine/blob/main/openingbook/store.py): `openingbook/store.py`
- [Game Reports](https://github.com/ethanchenhyland/funchessengine/blob/main/reporting/generator.py): `reporting/generator.py`

### Analysis Tools

- [Tournament Runner](https://github.com/ethanchenhyland/funchessengine/blob/main/integrations/tournament.py): `integrations/tournament.py`
- [External Engine Client](https://github.com/ethanchenhyland/funchessengine/blob/main/integrations/uci_client.py): `integrations/uci_client.py`
- [Match And Benchmark Tools](https://github.com/ethanchenhyland/funchessengine/blob/main/harness/arena.py): `harness/arena.py`

### Desktop Shell

- [Electron Shell](https://github.com/ethanchenhyland/funchessengine/blob/main/desktop/main.js): `desktop/main.js`
- [Desktop Metadata Store](https://github.com/ethanchenhyland/funchessengine/blob/main/desktop/storage.js): `desktop/storage.js`

### Other components

- **Local User**
- **Installed UCI Engine**

## Connections

- Local User → Engine Lab UI: uses
- Engine Lab UI → Local API: requests
- Local API → Move Search: searches positions
- Local API → Background Jobs: dispatches jobs
- Local API → Session Workspace: manages sessions
- Local User → Game And Review UI: plays and reviews
- Game And Review UI → Local API: requests
- Local API → Game Database: reads and writes
- Local API → Library Operations: handles library actions
- Library Operations → Game Catalog: queries catalog
- Game Catalog → Game Database: reads games
- Local User → Library Browser: browses games
- Library Browser → Local API: requests library data
- Local User → Opening Explorer: explores openings
- Opening Explorer → Local API: requests continuations
- Local API → Opening Repertoire: manages repertoire
- Local API → Game Reports: generates reports
- Workflow UI → Local API: requests workflows
- Local API → UCI Protocol: serves engine protocol
- UCI Protocol → Move Search: requests moves
- Local API → Tournament Runner: runs tournaments
- Tournament Runner → External Engine Client: compares engines
- External Engine Client → Installed UCI Engine: speaks UCI
- Match And Benchmark Tools → Move Search: evaluates matches
- Local User → Electron Shell: launches workstation
- Electron Shell → Local API: starts backend
- Electron Shell → Desktop Metadata Store: persists metadata