# sanderland/katrain architecture

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

- Interactive diagram: https://gitdiagram.com/sanderland/katrain
- Repository: https://github.com/sanderland/katrain

## Overview

1. KaTrain is a desktop Go client built around a local KataGo analysis engine. Its main purpose is to load or create games, maintain a move tree, query KataGo for analysis, and render that information in a Kivy-based GUI.

2. The top-level entrypoints are `katrain.py` and `katrain/__main__.py`, which boot the application package. The `katrain/core/base_katrain.py` module is the central application/controller layer that connects UI events, game state, engine access, configuration, and persistence.

3. The core game model lives in `katrain/core/game.py` and `katrain/core/game_node.py`. These modules represent the board position, move tree, branches, comments, and analysis annotations that appear in SGF review and teaching mode.

4. Engine integration is isolated in `katrain/core/engine.py` and `katrain/core/ai.py`. This is the boundary to KataGo: the app sends analysis requests, receives candidate moves/evaluations/ownership data, and uses those results both for review and for AI play. `katrain/core/contribute_engine.py` adds a separate engine mode for distributed training contribution.

5. File-format handling is in `katrain/core/sgf_parser.py`. SGF import/export is a major data path: games can be loaded from disk or clipboard, analyzed, edited in the move tree, and written back out with engine-derived annotations.

6. The GUI is a Kivy application defined by `katrain/gui.kv`, `katrain/popups.kv`, and the Python modules under `katrain/gui/`. `badukpan.py` is the board view, `controlspanel.py` handles the right-side controls and analysis panels, `popups.py` manages dialogs, and the widget modules provide specialized UI components such as file browsing, graphs, move-tree navigation, sliders, and progress display.

7. The main runtime flow is: user action in the GUI -> core game state update -> engine query if needed -> engine response -> UI redraw and annotation update. This same flow supports several modes: normal play, post-game analysis, teaching games, and continuous/“pondering” analysis.

8. The repository bundles its own KataGo runtime assets under `katrain/KataGo/`, including platform binaries and config files, plus a packaged model under `katrain/models/`. This means the app can ship as a self-contained desktop analyzer without requiring the user to assemble the engine separately, though the README notes that the engine command can also be overridden for remote or custom setups.

9. Localization is built in. The `katrain/i18n/` tree contains compiled and source message catalogs for multiple languages, and `i18n.py` plus `katrain/core/lang.py` support translation/runtime language selection. This is a user-facing subsystem rather than just documentation.

10. Visual customization is also packaged. `themes/` contains downloadable theme archives, while `katrain/gui/theme.py` and the KV layer define how colors, board appearance, and UI styling are applied. Fonts and flags are bundled under `katrain/fonts/` and `katrain/img/`.

11. Sound is a small but distinct subsystem under `katrain/sounds/` and `katrain/gui/sound.py`, used for move feedback and alerts during play and analysis. It is part of the user experience loop rather than core game logic.

12. The repo includes a significant amount of test and packaging infrastructure. `tests/` covers AI behavior, board/game logic, SGF parsing, and versioning; `spec/` contains packaging metadata for builds; `.github/workflows/` and custom GitHub actions automate CI and release-related tasks. This indicates the project is distributed as an end-user desktop application, not just a library.

Main entry points: [`katrain/core/base_katrain.py`](https://github.com/sanderland/katrain/blob/master/katrain/core/base_katrain.py) (App Core), [`katrain/core/engine.py`](https://github.com/sanderland/katrain/blob/master/katrain/core/engine.py) (KataGo Engine), [`katrain/gui/badukpan.py`](https://github.com/sanderland/katrain/blob/master/katrain/gui/badukpan.py) (Board View), [`tests/test_ai.py`](https://github.com/sanderland/katrain/blob/master/tests/test_ai.py) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_core["Core"]
  node_n_entry["Entrypoints<br/>bootstrap<br/>[katrain.py]"]
  node_n_pkgmain["Module Main<br/>bootstrap<br/>[__main__.py]"]
  node_n_app["App Core<br/>controller<br/>[base_katrain.py]"]
  node_n_game[("Game State<br/>model<br/>[game.py]")]
  node_n_node[("Move Node<br/>model<br/>[game_node.py]")]
  node_n_engine["KataGo Engine<br/>integration<br/>[engine.py]"]
  node_n_ai["AI Logic<br/>policy<br/>[ai.py]"]
  node_n_contrib["Contribute Mode<br/>engine mode"]
  node_n_sgf["SGF I/O<br/>parser<br/>[sgf_parser.py]"]
end

subgraph group_grp_gui["GUI"]
  node_n_board["Board View<br/>widget<br/>[badukpan.py]"]
  node_n_panel["Control Panel<br/>widget<br/>[controlspanel.py]"]
  node_n_dialogs["Dialogs<br/>[popups.py]"]
  node_n_theme["Themeing<br/>ui style<br/>[theme.py]"]
  node_n_widgets["Widgets<br/>[graph.py]"]
  node_n_kv["KV UI<br/>layout<br/>[gui.kv]"]
  node_n_popkv["Popup KV<br/>layout<br/>[popups.kv]"]
end

subgraph group_grp_assets["Assets"]
  node_n_lang["Language<br/>i18n<br/>[lang.py]"]
  node_n_runtime["KataGo Bundle<br/>runtime assets"]
  node_n_model[("Model Pack<br/>model asset")]
  node_n_i18n["Translations<br/>locales<br/>[katrain.po]"]
  node_n_sounds["Sounds<br/>audio assets<br/>[stone1.wav]"]
  node_n_themes["Themes<br/>asset packs<br/>[koast-theme.zip]"]
end

subgraph group_grp_ops["Ops"]
  node_n_tests["Tests<br/>test suite<br/>[test_ai.py]"]
  node_n_spec["Packaging<br/>build spec<br/>[KaTrain.spec]"]
  node_n_ci["CI Workflows<br/>automation"]
end

node_n_entry -->|"starts"| node_n_app
node_n_pkgmain -->|"starts"| node_n_app
node_n_app -->|"owns"| node_n_game
node_n_app -->|"queries"| node_n_engine
node_n_app -->|"loads/saves"| node_n_sgf
node_n_app -->|"drives"| node_n_board
node_n_app -->|"drives"| node_n_panel
node_n_game -->|"contains"| node_n_node
node_n_ai -->|"uses"| node_n_engine
node_n_contrib -->|"specializes"| node_n_engine
node_n_engine -->|"runs"| node_n_runtime
node_n_engine -->|"loads"| node_n_model
node_n_sgf -->|"serializes"| node_n_game
node_n_sgf -->|"annotates"| node_n_node
node_n_board -->|"styles"| node_n_theme
node_n_panel -->|"composes"| node_n_widgets
node_n_dialogs -->|"binds"| node_n_popkv
node_n_board -->|"binds"| node_n_kv
node_n_panel -->|"binds"| node_n_kv
node_n_lang -->|"uses"| node_n_i18n
node_n_app -->|"selects"| node_n_lang
node_n_board -->|"plays"| node_n_sounds
node_n_tests -->|"verifies"| node_n_game
node_n_tests -->|"verifies"| node_n_sgf
node_n_tests -->|"verifies"| node_n_ai
node_n_spec -->|"packages"| node_n_runtime
node_n_spec -->|"packages"| node_n_model
node_n_ci -->|"runs"| node_n_tests
node_n_ci -->|"builds"| node_n_spec

click node_n_entry "https://github.com/sanderland/katrain/blob/master/katrain.py"
click node_n_pkgmain "https://github.com/sanderland/katrain/blob/master/katrain/__main__.py"
click node_n_app "https://github.com/sanderland/katrain/blob/master/katrain/core/base_katrain.py"
click node_n_game "https://github.com/sanderland/katrain/blob/master/katrain/core/game.py"
click node_n_node "https://github.com/sanderland/katrain/blob/master/katrain/core/game_node.py"
click node_n_engine "https://github.com/sanderland/katrain/blob/master/katrain/core/engine.py"
click node_n_ai "https://github.com/sanderland/katrain/blob/master/katrain/core/ai.py"
click node_n_contrib "https://github.com/sanderland/katrain/blob/master/katrain/core/contribute_engine.py"
click node_n_sgf "https://github.com/sanderland/katrain/blob/master/katrain/core/sgf_parser.py"
click node_n_lang "https://github.com/sanderland/katrain/blob/master/katrain/core/lang.py"
click node_n_board "https://github.com/sanderland/katrain/blob/master/katrain/gui/badukpan.py"
click node_n_panel "https://github.com/sanderland/katrain/blob/master/katrain/gui/controlspanel.py"
click node_n_dialogs "https://github.com/sanderland/katrain/blob/master/katrain/gui/popups.py"
click node_n_theme "https://github.com/sanderland/katrain/blob/master/katrain/gui/theme.py"
click node_n_widgets "https://github.com/sanderland/katrain/blob/master/katrain/gui/widgets/graph.py"
click node_n_kv "https://github.com/sanderland/katrain/blob/master/katrain/gui.kv"
click node_n_popkv "https://github.com/sanderland/katrain/blob/master/katrain/popups.kv"
click node_n_runtime "https://github.com/sanderland/katrain/tree/master/katrain/KataGo/katago"
click node_n_model "https://github.com/sanderland/katrain/blob/master/katrain/models/kata1-b18c384nbt-s9996604416-d4316597426.bin.gz"
click node_n_i18n "https://github.com/sanderland/katrain/blob/master/katrain/i18n/locales/en/LC_MESSAGES/katrain.po"
click node_n_sounds "https://github.com/sanderland/katrain/blob/master/katrain/sounds/stone1.wav"
click node_n_themes "https://github.com/sanderland/katrain/blob/master/themes/koast-theme.zip"
click node_n_tests "https://github.com/sanderland/katrain/blob/master/tests/test_ai.py"
click node_n_spec "https://github.com/sanderland/katrain/blob/master/spec/KaTrain.spec"
click node_n_ci "https://github.com/sanderland/katrain/blob/master/.github/workflows/test_and_build.yaml"

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_n_entry,node_n_pkgmain,node_n_app,node_n_game,node_n_node,node_n_engine,node_n_ai,node_n_contrib,node_n_sgf toneBlue
class node_n_board,node_n_panel,node_n_dialogs,node_n_theme,node_n_widgets,node_n_kv,node_n_popkv toneAmber
class node_n_lang,node_n_runtime,node_n_model,node_n_i18n,node_n_sounds,node_n_themes toneMint
class node_n_tests,node_n_spec,node_n_ci toneRose
```

## Components

### Core

Application controller, game model, engine integration, and file format handling.

- [Entrypoints](https://github.com/sanderland/katrain/blob/master/katrain.py): bootstrap · Top-level launch scripts that start the application package. · `katrain.py`
- [Module Main](https://github.com/sanderland/katrain/blob/master/katrain/__main__.py): bootstrap · Package entrypoint used for module execution. · `katrain/__main__.py`
- [App Core](https://github.com/sanderland/katrain/blob/master/katrain/core/base_katrain.py): controller · Main application/controller layer wiring UI, game state, engine access, config, and persistence. · `katrain/core/base_katrain.py`
- [Game State](https://github.com/sanderland/katrain/blob/master/katrain/core/game.py): model · Board position, move tree, branches, comments, and annotations. · `katrain/core/game.py`
- [Move Node](https://github.com/sanderland/katrain/blob/master/katrain/core/game_node.py): model · Per-node move metadata and analysis annotations in the tree. · `katrain/core/game_node.py`
- [KataGo Engine](https://github.com/sanderland/katrain/blob/master/katrain/core/engine.py): integration · Boundary for sending analysis requests and receiving evaluations, ownership, and candidates. · `katrain/core/engine.py`
- [AI Logic](https://github.com/sanderland/katrain/blob/master/katrain/core/ai.py): policy · Analysis consumption and AI move selection built on engine output. · `katrain/core/ai.py`
- [Contribute Mode](https://github.com/sanderland/katrain/blob/master/katrain/core/contribute_engine.py): engine mode · Distributed training contribution engine path. · `katrain/core/contribute_engine.py`
- [SGF I/O](https://github.com/sanderland/katrain/blob/master/katrain/core/sgf_parser.py): parser · Import/export of games and engine annotations through SGF. · `katrain/core/sgf_parser.py`

### GUI

Kivy widgets, board rendering, dialogs, and theming.

- [Board View](https://github.com/sanderland/katrain/blob/master/katrain/gui/badukpan.py): widget · Main board rendering and interaction surface. · `katrain/gui/badukpan.py`
- [Control Panel](https://github.com/sanderland/katrain/blob/master/katrain/gui/controlspanel.py): widget · Side controls, analysis panels, and play/review actions. · `katrain/gui/controlspanel.py`
- [Dialogs](https://github.com/sanderland/katrain/blob/master/katrain/gui/popups.py): ui dialogs · Popups and dialog flow for file, settings, and status interactions. · `katrain/gui/popups.py`
- [Themeing](https://github.com/sanderland/katrain/blob/master/katrain/gui/theme.py): ui style · Color, board appearance, and UI styling logic. · `katrain/gui/theme.py`
- [Widgets](https://github.com/sanderland/katrain/blob/master/katrain/gui/widgets/graph.py): ui widgets · Specialized supporting widgets such as file browsing, graphs, move-tree navigation, sliders, and progress display. · `katrain/gui/widgets/graph.py`
- [KV UI](https://github.com/sanderland/katrain/blob/master/katrain/gui.kv): layout · Kivy declarative UI definitions for the main screen and dialogs. · `katrain/gui.kv`
- [Popup KV](https://github.com/sanderland/katrain/blob/master/katrain/popups.kv): layout · Declarative popup/dialog layout definitions. · `katrain/popups.kv`

### Assets

Bundled runtime assets, localization, media, and downloadable themes.

- [Language](https://github.com/sanderland/katrain/blob/master/katrain/core/lang.py): i18n · Runtime language selection and translation support. · `katrain/core/lang.py`
- [KataGo Bundle](https://github.com/sanderland/katrain/tree/master/katrain/KataGo/katago): runtime assets · Packaged KataGo binaries and configs shipped with the app. · `katrain/KataGo/katago`
- [Model Pack](https://github.com/sanderland/katrain/blob/master/katrain/models/kata1-b18c384nbt-s9996604416-d4316597426.bin.gz): model asset · Bundled KataGo network model used for local analysis. · `katrain/models/kata1-b18c384nbt-s9996604416-d4316597426.bin.gz`
- [Translations](https://github.com/sanderland/katrain/blob/master/katrain/i18n/locales/en/LC_MESSAGES/katrain.po): locales · Compiled and source message catalogs for multiple languages. · `katrain/i18n/locales/en/LC_MESSAGES/katrain.po`
- [Sounds](https://github.com/sanderland/katrain/blob/master/katrain/sounds/stone1.wav): audio assets · Move feedback and alert sound effects. · `katrain/sounds/stone1.wav`
- [Themes](https://github.com/sanderland/katrain/blob/master/themes/koast-theme.zip): asset packs · Packaged downloadable theme archives. · `themes/koast-theme.zip`

### Ops

Tests, packaging, and CI/release automation.

- [Tests](https://github.com/sanderland/katrain/blob/master/tests/test_ai.py): test suite · Coverage for AI behavior, board/game logic, SGF parsing, and versioning. · `tests/test_ai.py`
- [Packaging](https://github.com/sanderland/katrain/blob/master/spec/KaTrain.spec): build spec · Build and packaging metadata for desktop distribution. · `spec/KaTrain.spec`
- [CI Workflows](https://github.com/sanderland/katrain/blob/master/.github/workflows/test_and_build.yaml): automation · GitHub Actions workflows for testing, building, and release-related automation. · `.github/workflows/test_and_build.yaml`

## Connections

- Entrypoints → App Core: starts · Launch script bootstraps the main app controller.
- Module Main → App Core: starts · Module execution enters the same application controller.
- App Core → Game State: owns · Controller maintains current game state and move tree.
- App Core → KataGo Engine: queries · Controller sends analysis requests and receives responses.
- App Core → SGF I/O: loads/saves · Controller orchestrates import, export, and persistence.
- App Core → Board View: drives · Controller updates board UI from state changes.
- App Core → Control Panel: drives · Controller feeds control and analysis panels.
- Game State → Move Node: contains · Game state is structured as a move tree of nodes.
- AI Logic → KataGo Engine: uses · AI logic depends on engine analysis outputs.
- Contribute Mode → KataGo Engine: specializes · Contribution mode wraps the engine boundary with a distinct workflow.
- KataGo Engine → KataGo Bundle: runs · Engine integration targets bundled KataGo binaries and configs.
- KataGo Engine → Model Pack: loads · Engine uses the packaged analysis model.
- SGF I/O → Game State: serializes · SGF parsing maps files into and out of game state.
- SGF I/O → Move Node: annotates · SGF export/import preserves node-level comments and analysis.
- Board View → Themeing: styles · Board view is styled by theme logic.
- Control Panel → Widgets: composes · Control panel is built from shared widget components.
- Dialogs → Popup KV: binds · Popup logic pairs with popup KV layout definitions.
- Board View → KV UI: binds · Main UI layout defines board placement and interactions.
- Control Panel → KV UI: binds · Main UI layout defines control panel structure.
- Language → Translations: uses · Runtime language selection consumes message catalogs.
- App Core → Language: selects · Application controller coordinates localization setup.
- Board View → Sounds: plays · Move feedback and alerts use packaged sounds.
- Tests → Game State: verifies · Tests cover core game logic.
- Tests → SGF I/O: verifies · Tests cover SGF parsing and export paths.
- Tests → AI Logic: verifies · Tests cover AI behavior and engine-facing logic.
- Packaging → KataGo Bundle: packages · Build spec includes bundled engine runtime assets.
- Packaging → Model Pack: packages · Build spec includes the packaged model.
- CI Workflows → Tests: runs · Workflows execute the test suite.
- CI Workflows → Packaging: builds · Workflows drive packaging and build validation.
