# merrick-shen/horyx-games architecture

> Architecture diagram of the GitHub repository merrick-shen/horyx-games, 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/merrick-shen/horyx-games
- Repository: https://github.com/merrick-shen/horyx-games

## Overview

Horyx Games is a cross-platform Flutter app that brings together five local games, several LAN multiplayer games, settings and saved-game management. The main user workflow is to browse the game catalog, open a game, configure or resume it, and play; multiplayer games additionally join or host a room and exchange game state over TCP. The README documents the feature boundaries and shared services; sampled native files mainly show platform launch plumbing, so detailed Dart call ownership is not verified here.

Main entry points: [`lib/app/pages/home_page.dart`](https://github.com/merrick-shen/horyx-games/blob/main/lib/app/pages/home_page.dart) (Game catalog UI), [`lib/shared/storage/archive_storage.dart`](https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/storage/archive_storage.dart) (Game archives), [`lib/main.dart`](https://github.com/merrick-shen/horyx-games/blob/main/lib/main.dart) (App bootstrap), [`lib/app/pages/settings`](https://github.com/merrick-shen/horyx-games/tree/main/lib/app/pages/settings) (Settings pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_entry["App bootstrap<br/>[main.dart]"]
  node_shell["Navigation shell<br/>[app_shell.dart]"]
  node_catalog["Game registry<br/>[game_registry.dart]"]
  node_home["Game catalog UI<br/>[home_page.dart]"]
  node_archive_ui["Archive settings<br/>[archive_page.dart]"]
  node_settings["Settings pages"]
end

subgraph group_games["Game features"]
  node_chess["Chinese chess"]
  node_gomoku["Gomoku"]
  node_tank["Tank battle"]
  node_tank_engine["Tank engine"]
  node_wordpk["Word PK"]
  node_scoreboard["Scoreboard"]
end

subgraph group_network["LAN multiplayer"]
  node_online_pages["Room pages"]
  node_online_base["Online controllers"]
  node_board_online["Board-game controller"]
  node_room_io["TCP room transport<br/>[room_client.dart]"]
  node_qr["QR scan page<br/>[qr_scan_page.dart]"]
end

subgraph group_shared["Shared services"]
  node_game_storage[("Game archives")]
  node_profile["Profile service"]
  node_theme["Theme service"]
end

subgraph group_updates["Update service"]
  node_updates["Update checker"]
end

node_user(("Player"))
node_peer(("LAN peer"))
node_preferences[("Local preferences")]
node_release_api["GitHub Releases"]

node_user -->|"launches"| node_entry
node_entry -->|"starts"| node_shell
node_user -->|"browses"| node_home
node_shell -->|"shows"| node_home
node_home -->|"lists games"| node_catalog
node_home -->|"opens"| node_chess
node_home -->|"opens"| node_gomoku
node_home -->|"opens"| node_tank
node_home -->|"opens"| node_wordpk
node_home -->|"opens"| node_scoreboard
node_chess -->|"saves games"| node_game_storage
node_gomoku -->|"saves games"| node_game_storage
node_tank -->|"saves games"| node_game_storage
node_wordpk -->|"saves games"| node_game_storage
node_scoreboard -->|"saves games"| node_game_storage
node_tank -->|"runs battle"| node_tank_engine
node_chess -->|"uses multiplayer"| node_board_online
node_gomoku -->|"uses multiplayer"| node_board_online
node_wordpk -->|"uses multiplayer"| node_online_base
node_tank -->|"uses multiplayer"| node_online_base
node_online_pages -->|"hosts or joins"| node_room_io
node_online_base -->|"exchanges state"| node_room_io
node_board_online -->|"extends"| node_online_base
node_room_io -->|"sends TCP"| node_peer
node_peer -->|"sends TCP"| node_room_io
node_user -->|"joins room"| node_online_pages
node_user -->|"scans room"| node_qr
node_qr -->|"provides room code"| node_online_pages
node_user -->|"manages saves"| node_archive_ui
node_archive_ui -->|"reads or deletes"| node_game_storage
node_user -->|"configures app"| node_settings
node_entry -->|"restores username"| node_profile
node_entry -->|"restores theme"| node_theme
node_settings -->|"edits profile"| node_profile
node_settings -->|"changes theme"| node_theme
node_profile -->|"persists profile"| node_preferences
node_theme -->|"persists theme"| node_preferences
node_settings -->|"checks version"| node_updates
node_updates -->|"queries releases"| node_release_api

click node_entry "https://github.com/merrick-shen/horyx-games/blob/main/lib/main.dart"
click node_shell "https://github.com/merrick-shen/horyx-games/blob/main/lib/app/app_shell.dart"
click node_catalog "https://github.com/merrick-shen/horyx-games/blob/main/lib/app/game_registry.dart"
click node_home "https://github.com/merrick-shen/horyx-games/blob/main/lib/app/pages/home_page.dart"
click node_archive_ui "https://github.com/merrick-shen/horyx-games/blob/main/lib/app/pages/settings/archive_page.dart"
click node_settings "https://github.com/merrick-shen/horyx-games/tree/main/lib/app/pages/settings"
click node_chess "https://github.com/merrick-shen/horyx-games/tree/main/lib/games/chess"
click node_gomoku "https://github.com/merrick-shen/horyx-games/tree/main/lib/games/gomoku"
click node_tank "https://github.com/merrick-shen/horyx-games/tree/main/lib/games/tank"
click node_tank_engine "https://github.com/merrick-shen/horyx-games/blob/main/lib/games/tank/engine/tank_maze_game.dart"
click node_wordpk "https://github.com/merrick-shen/horyx-games/tree/main/lib/games/word_pk"
click node_scoreboard "https://github.com/merrick-shen/horyx-games/tree/main/lib/games/scoreboard"
click node_online_pages "https://github.com/merrick-shen/horyx-games/tree/main/lib/shared/pages"
click node_online_base "https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/network/online_game_controller.dart"
click node_board_online "https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/network/board_game_online_controller.dart"
click node_room_io "https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/network/room_client.dart"
click node_game_storage "https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/storage/archive_storage.dart"
click node_profile "https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/profile/profile_controller.dart"
click node_theme "https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/theme/theme_controller.dart"
click node_updates "https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/update/update_service.dart"
click node_qr "https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/pages/qr_scan_page.dart"

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_entry,node_shell,node_catalog,node_home,node_archive_ui,node_settings toneBlue
class node_chess,node_gomoku,node_tank,node_tank_engine,node_wordpk,node_scoreboard,node_preferences toneAmber
class node_online_pages,node_online_base,node_board_online,node_room_io,node_qr toneMint
class node_game_storage,node_profile,node_theme toneRose
class node_updates,node_user,node_peer,node_release_api toneIndigo
```

## Components

### App shell

- [App bootstrap](https://github.com/merrick-shen/horyx-games/blob/main/lib/main.dart): `lib/main.dart`
- [Navigation shell](https://github.com/merrick-shen/horyx-games/blob/main/lib/app/app_shell.dart): `lib/app/app_shell.dart`
- [Game registry](https://github.com/merrick-shen/horyx-games/blob/main/lib/app/game_registry.dart): `lib/app/game_registry.dart`
- [Game catalog UI](https://github.com/merrick-shen/horyx-games/blob/main/lib/app/pages/home_page.dart): `lib/app/pages/home_page.dart`
- [Archive settings](https://github.com/merrick-shen/horyx-games/blob/main/lib/app/pages/settings/archive_page.dart): `lib/app/pages/settings/archive_page.dart`
- [Settings pages](https://github.com/merrick-shen/horyx-games/tree/main/lib/app/pages/settings): `lib/app/pages/settings`

### Game features

- [Chinese chess](https://github.com/merrick-shen/horyx-games/tree/main/lib/games/chess): `lib/games/chess`
- [Gomoku](https://github.com/merrick-shen/horyx-games/tree/main/lib/games/gomoku): `lib/games/gomoku`
- [Tank battle](https://github.com/merrick-shen/horyx-games/tree/main/lib/games/tank): `lib/games/tank`
- [Tank engine](https://github.com/merrick-shen/horyx-games/blob/main/lib/games/tank/engine/tank_maze_game.dart): `lib/games/tank/engine/tank_maze_game.dart`
- [Word PK](https://github.com/merrick-shen/horyx-games/tree/main/lib/games/word_pk): `lib/games/word_pk`
- [Scoreboard](https://github.com/merrick-shen/horyx-games/tree/main/lib/games/scoreboard): `lib/games/scoreboard`

### LAN multiplayer

- [Room pages](https://github.com/merrick-shen/horyx-games/tree/main/lib/shared/pages): `lib/shared/pages`
- [Online controllers](https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/network/online_game_controller.dart): `lib/shared/network/online_game_controller.dart`
- [Board-game controller](https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/network/board_game_online_controller.dart): `lib/shared/network/board_game_online_controller.dart`
- [TCP room transport](https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/network/room_client.dart): `lib/shared/network/room_client.dart`
- [QR scan page](https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/pages/qr_scan_page.dart): `lib/shared/pages/qr_scan_page.dart`

### Shared services

- [Game archives](https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/storage/archive_storage.dart): `lib/shared/storage/archive_storage.dart`
- [Profile service](https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/profile/profile_controller.dart): `lib/shared/profile/profile_controller.dart`
- [Theme service](https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/theme/theme_controller.dart): `lib/shared/theme/theme_controller.dart`

### Update service

- [Update checker](https://github.com/merrick-shen/horyx-games/blob/main/lib/shared/update/update_service.dart): `lib/shared/update/update_service.dart`

### Other components

- **Player**
- **LAN peer**
- **Local preferences**
- **GitHub Releases**

## Connections

- Player → App bootstrap: launches
- App bootstrap → Navigation shell: starts
- Player → Game catalog UI: browses
- Navigation shell → Game catalog UI: shows
- Game catalog UI → Game registry: lists games
- Game catalog UI → Chinese chess: opens
- Game catalog UI → Gomoku: opens
- Game catalog UI → Tank battle: opens
- Game catalog UI → Word PK: opens
- Game catalog UI → Scoreboard: opens
- Chinese chess → Game archives: saves games
- Gomoku → Game archives: saves games
- Tank battle → Game archives: saves games
- Word PK → Game archives: saves games
- Scoreboard → Game archives: saves games
- Tank battle → Tank engine: runs battle
- Chinese chess → Board-game controller: uses multiplayer
- Gomoku → Board-game controller: uses multiplayer
- Word PK → Online controllers: uses multiplayer
- Tank battle → Online controllers: uses multiplayer
- Room pages → TCP room transport: hosts or joins
- Online controllers → TCP room transport: exchanges state
- Board-game controller → Online controllers: extends
- TCP room transport → LAN peer: sends TCP
- LAN peer → TCP room transport: sends TCP
- Player → Room pages: joins room
- Player → QR scan page: scans room
- QR scan page → Room pages: provides room code
- Player → Archive settings: manages saves
- Archive settings → Game archives: reads or deletes
- Player → Settings pages: configures app
- App bootstrap → Profile service: restores username
- App bootstrap → Theme service: restores theme
- Settings pages → Profile service: edits profile
- Settings pages → Theme service: changes theme
- Profile service → Local preferences: persists profile
- Theme service → Local preferences: persists theme
- Settings pages → Update checker: checks version
- Update checker → GitHub Releases: queries releases