# monster-cli/dsh-whileplay architecture

> Architecture diagram of the GitHub repository monster-cli/dsh-whileplay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monster-cli/dsh-whileplay
- Repository: https://github.com/monster-cli/dsh-whileplay

## Overview

Whileplay is a DeepSeek Harness Web game plugin: users open a floating game window, play task-linked action games or local board games, and can follow live session progress during play. The documented expedition workflow projects session events into a bounded read model, presents that task context alongside an escort battle, and saves progress per session. The excerpts show the plugin’s projection registration and several simulation-module calls; UI wiring and some documented capabilities are represented from the README, not inspected source.

Main entry points: [`src/engine.js`](https://github.com/monster-cli/dsh-whileplay/blob/main/src/engine.js) (Game engine), [`client.js`](https://github.com/monster-cli/dsh-whileplay/blob/main/client.js) (Web client), [`src/escort-action.js`](https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-action.js) (Escort battle), [`index.js`](https://github.com/monster-cli/dsh-whileplay/blob/main/index.js) (Plugin entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Harness integration"]
  node_plugin["Plugin entry<br/>[index.js]"]
  node_mission_projection["Task projection<br/>[mission.js]"]
  node_escort_projection["Expedition projection<br/>[escort-mission.js]"]
end

subgraph group_interface["Game interface"]
  node_client["Web client<br/>[client.js]"]
  node_window["Game window<br/>[window.js]"]
  node_ui["Game controls<br/>[ui.js]"]
end

subgraph group_arcade["Arcade gameplay"]
  node_engine["Game engine<br/>[engine.js]"]
  node_flight["Flight progression<br/>[flight.js]"]
  node_mission_game["Mission combat<br/>[mission-game.js]"]
  node_ground_mission["Ground mission events<br/>[ground-mission.js]"]
  node_tank["Tank simulation<br/>[tank.js]"]
  node_flight_save[("Flight saves<br/>[flight-save.js]")]
end

subgraph group_expedition["Escort expedition"]
  node_expedition_action["Escort battle<br/>[escort-action.js]"]
  node_expedition_live["Live task context<br/>[escort-live.js]"]
  node_expedition_task["Task briefing<br/>[escort-task.js]"]
  node_expedition_terrain["Route and terrain<br/>[escort-terrain.js]"]
  node_expedition_art["Battle artwork<br/>[escort-art.js]"]
end

subgraph group_board["Board games"]
  node_board_ui["Board interface<br/>[board-ui.js]"]
  node_board_games["Board game logic<br/>[board-games.js]"]
  node_xiangqi["Xiangqi engine<br/>[xiangqi.js]"]
end

node_player(("Player"))
node_harness[("Harness session")]

node_player -->|"opens games"| node_client
node_harness -.->|"emits session events"| node_plugin
node_plugin -->|"registers fold"| node_mission_projection
node_plugin -->|"registers fold"| node_escort_projection
node_player -->|"moves and resizes"| node_window
node_client -.->|"runs games"| node_engine
node_client -.->|"opens board play"| node_board_ui
node_client -.->|"shows session status"| node_expedition_live
node_engine -->|"steps and draws"| node_tank
node_engine -->|"steps and draws"| node_mission_game
node_engine -->|"steps and draws"| node_ground_mission
node_engine -->|"creates flight state"| node_flight
node_mission_game -->|"updates progression"| node_flight
node_engine -->|"creates escort state"| node_expedition_action
node_expedition_action -->|"uses route and terrain"| node_expedition_terrain
node_expedition_action -->|"draws battle assets"| node_expedition_art
node_expedition_action -->|"draws task briefing"| node_expedition_task
node_expedition_task -->|"reads route stage"| node_expedition_terrain
node_board_ui -.->|"handles board play"| node_board_games
node_board_games -->|"uses rules engine"| node_xiangqi
node_client -.->|"saves flight progress"| node_flight_save

click node_plugin "https://github.com/monster-cli/dsh-whileplay/blob/main/index.js"
click node_mission_projection "https://github.com/monster-cli/dsh-whileplay/blob/main/mission.js"
click node_escort_projection "https://github.com/monster-cli/dsh-whileplay/blob/main/escort-mission.js"
click node_client "https://github.com/monster-cli/dsh-whileplay/blob/main/client.js"
click node_window "https://github.com/monster-cli/dsh-whileplay/blob/main/src/window.js"
click node_ui "https://github.com/monster-cli/dsh-whileplay/blob/main/src/ui.js"
click node_engine "https://github.com/monster-cli/dsh-whileplay/blob/main/src/engine.js"
click node_flight "https://github.com/monster-cli/dsh-whileplay/blob/main/src/flight.js"
click node_mission_game "https://github.com/monster-cli/dsh-whileplay/blob/main/src/mission-game.js"
click node_ground_mission "https://github.com/monster-cli/dsh-whileplay/blob/main/src/ground-mission.js"
click node_tank "https://github.com/monster-cli/dsh-whileplay/blob/main/src/tank.js"
click node_expedition_action "https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-action.js"
click node_expedition_live "https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-live.js"
click node_expedition_task "https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-task.js"
click node_expedition_terrain "https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-terrain.js"
click node_expedition_art "https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-art.js"
click node_flight_save "https://github.com/monster-cli/dsh-whileplay/blob/main/src/flight-save.js"
click node_board_ui "https://github.com/monster-cli/dsh-whileplay/blob/main/src/board-ui.js"
click node_board_games "https://github.com/monster-cli/dsh-whileplay/blob/main/src/board-games.js"
click node_xiangqi "https://github.com/monster-cli/dsh-whileplay/blob/main/src/xiangqi.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_plugin,node_mission_projection,node_escort_projection toneBlue
class node_client,node_window,node_ui,node_harness toneAmber
class node_engine,node_flight,node_mission_game,node_ground_mission,node_tank,node_flight_save toneMint
class node_expedition_action,node_expedition_live,node_expedition_task,node_expedition_terrain,node_expedition_art toneRose
class node_board_ui,node_board_games,node_xiangqi,node_player toneIndigo
```

## Components

### Harness integration

- [Plugin entry](https://github.com/monster-cli/dsh-whileplay/blob/main/index.js): `index.js`
- [Task projection](https://github.com/monster-cli/dsh-whileplay/blob/main/mission.js): `mission.js`
- [Expedition projection](https://github.com/monster-cli/dsh-whileplay/blob/main/escort-mission.js): `escort-mission.js`

### Game interface

- [Web client](https://github.com/monster-cli/dsh-whileplay/blob/main/client.js): `client.js`
- [Game window](https://github.com/monster-cli/dsh-whileplay/blob/main/src/window.js): `src/window.js`
- [Game controls](https://github.com/monster-cli/dsh-whileplay/blob/main/src/ui.js): `src/ui.js`

### Arcade gameplay

- [Game engine](https://github.com/monster-cli/dsh-whileplay/blob/main/src/engine.js): `src/engine.js`
- [Flight progression](https://github.com/monster-cli/dsh-whileplay/blob/main/src/flight.js): `src/flight.js`
- [Mission combat](https://github.com/monster-cli/dsh-whileplay/blob/main/src/mission-game.js): `src/mission-game.js`
- [Ground mission events](https://github.com/monster-cli/dsh-whileplay/blob/main/src/ground-mission.js): `src/ground-mission.js`
- [Tank simulation](https://github.com/monster-cli/dsh-whileplay/blob/main/src/tank.js): `src/tank.js`
- [Flight saves](https://github.com/monster-cli/dsh-whileplay/blob/main/src/flight-save.js): `src/flight-save.js`

### Escort expedition

- [Escort battle](https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-action.js): `src/escort-action.js`
- [Live task context](https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-live.js): `src/escort-live.js`
- [Task briefing](https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-task.js): `src/escort-task.js`
- [Route and terrain](https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-terrain.js): `src/escort-terrain.js`
- [Battle artwork](https://github.com/monster-cli/dsh-whileplay/blob/main/src/escort-art.js): `src/escort-art.js`

### Board games

- [Board interface](https://github.com/monster-cli/dsh-whileplay/blob/main/src/board-ui.js): `src/board-ui.js`
- [Board game logic](https://github.com/monster-cli/dsh-whileplay/blob/main/src/board-games.js): `src/board-games.js`
- [Xiangqi engine](https://github.com/monster-cli/dsh-whileplay/blob/main/src/xiangqi.js): `src/xiangqi.js`

### Other components

- **Player**
- **Harness session**

## Connections

- Player → Web client: opens games (evidence: `README.md`)
- Harness session → Plugin entry: emits session events
- Plugin entry → Task projection: registers fold (evidence: `index.js`)
- Plugin entry → Expedition projection: registers fold (evidence: `index.js`)
- Player → Game window: moves and resizes (evidence: `README.md`)
- Web client → Game engine: runs games
- Web client → Board interface: opens board play
- Web client → Live task context: shows session status
- Game engine → Tank simulation: steps and draws (evidence: `src/engine.js`)
- Game engine → Mission combat: steps and draws (evidence: `src/engine.js`)
- Game engine → Ground mission events: steps and draws (evidence: `src/engine.js`)
- Game engine → Flight progression: creates flight state (evidence: `src/engine.js`)
- Mission combat → Flight progression: updates progression (evidence: `src/mission-game.js`)
- Game engine → Escort battle: creates escort state (evidence: `src/engine.js`)
- Escort battle → Route and terrain: uses route and terrain (evidence: `src/escort-action.js`)
- Escort battle → Battle artwork: draws battle assets (evidence: `src/escort-action.js`)
- Escort battle → Task briefing: draws task briefing (evidence: `src/escort-action.js`)
- Task briefing → Route and terrain: reads route stage (evidence: `src/escort-task.js`)
- Board interface → Board game logic: handles board play
- Board game logic → Xiangqi engine: uses rules engine (evidence: `src/board-games.js`)
- Web client → Flight saves: saves flight progress
