# kershner/daggerwalk architecture

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

- Interactive diagram: https://gitdiagram.com/kershner/daggerwalk
- Repository: https://github.com/kershner/daggerwalk

## Overview

Daggerwalk runs a shared Twitch-driven game session: chat commands become game actions, while the bot reads game state and publishes stream updates. A local control page reuses the bot command handler. The repository also includes DFU mods for automation, camera, music, map logging, and gameplay changes. Edges reflect README statements or shown calls; some mod capabilities are documented by the tree and README but their runtime wiring was not sampled, so those links are omitted.

Main entry points: [`daggerwalk/twitch_bot.py`](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/twitch_bot.py) (Command and session bot), [`daggerwalk/dev_server.py`](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/dev_server.py) (Dev HTTP server), [`daggerwalk/supervisor.py`](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/supervisor.py) (Supervisor), [`daggerwalk/bluesky.py`](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/bluesky.py) (Status and milestone posts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Interfaces"]
  node_dev_page["Dev control page<br/>[dev_control.html]"]
  node_dev_server["Dev HTTP server<br/>[dev_server.py]"]
  node_supervisor["Supervisor<br/>[supervisor.py]"]
end

subgraph group_bot["Bot Runtime"]
  node_bot["Command and session bot<br/>[twitch_bot.py]"]
  node_paths["Runtime paths<br/>[paths.py]"]
  node_herald["Milestone formatting<br/>[herald.py]"]
  node_cinematic_client["Camera control client<br/>[cinematic.py]"]
  node_runtime_state[("Runtime state and logs<br/>[paths.py]")]
end

subgraph group_game["Game Automation"]
end

subgraph group_mods["DFU Mods"]
  node_dfu_mods["Gameplay mods"]
  node_camera_mod["Cinematic camera mod<br/>[CinematicCamera.cs]"]
  node_music_mod["Music changer<br/>[MusicChanger.cs]"]
  node_map_logger["Map data logger<br/>[MapDataLogger.cs]"]
end

subgraph group_publish["Stream Publishing"]
  node_bluesky["Status and milestone posts<br/>[bluesky.py]"]
end

node_viewers(("Twitch chat"))
node_dev_user(("Local control user"))
node_twitch(("Twitch platform"))
node_game_process(("Daggerfall Unity"))
node_obs(("OBS stream"))
node_bluesky_service(("Bluesky"))

node_viewers -->|"send commands"| node_bot
node_bot -->|"connects to"| node_twitch
node_bot -->|"automates gameplay"| node_game_process
node_dev_user -->|"uses controls"| node_dev_page
node_dev_page -->|"requests controls"| node_dev_server
node_dev_server -->|"dispatches commands"| node_bot
node_bot -->|"sends feedback"| node_dev_server
node_supervisor -->|"starts and stages"| node_game_process
node_supervisor -->|"launches or recovers"| node_bot
node_supervisor -->|"launches dev mode"| node_dev_server
node_bot -->|"uses shared paths"| node_paths
node_paths -->|"defines locations"| node_runtime_state
node_bot -->|"formats milestones"| node_herald
node_bluesky -->|"formats announcements"| node_herald
node_bot -->|"requests camera state"| node_cinematic_client
node_cinematic_client -->|"exchanges status requests"| node_camera_mod
node_camera_mod -->|"controls camera"| node_game_process
node_music_mod -->|"changes music"| node_game_process
node_map_logger -->|"logs map data"| node_game_process
node_dfu_mods -->|"adds gameplay features"| node_game_process
node_bot -.->|"updates stream"| node_obs
node_bot -.->|"publishes updates"| node_bluesky
node_bluesky -->|"posts status"| node_bluesky_service

click node_dev_page "https://github.com/kershner/daggerwalk/blob/master/daggerwalk/templates/dev_control.html"
click node_dev_server "https://github.com/kershner/daggerwalk/blob/master/daggerwalk/dev_server.py"
click node_supervisor "https://github.com/kershner/daggerwalk/blob/master/daggerwalk/supervisor.py"
click node_bot "https://github.com/kershner/daggerwalk/blob/master/daggerwalk/twitch_bot.py"
click node_paths "https://github.com/kershner/daggerwalk/blob/master/daggerwalk/paths.py"
click node_herald "https://github.com/kershner/daggerwalk/blob/master/daggerwalk/herald.py"
click node_cinematic_client "https://github.com/kershner/daggerwalk/blob/master/daggerwalk/cinematic.py"
click node_runtime_state "https://github.com/kershner/daggerwalk/blob/master/daggerwalk/paths.py"
click node_dfu_mods "https://github.com/kershner/daggerwalk/tree/master/mods/dfu"
click node_camera_mod "https://github.com/kershner/daggerwalk/blob/master/mods/dfu/CinematicCamera.cs"
click node_music_mod "https://github.com/kershner/daggerwalk/blob/master/mods/dfu/MusicChanger.cs"
click node_map_logger "https://github.com/kershner/daggerwalk/blob/master/mods/dfu/MapDataLogger.cs"
click node_bluesky "https://github.com/kershner/daggerwalk/blob/master/daggerwalk/bluesky.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_dev_page,node_dev_server,node_supervisor,node_dev_user toneBlue
class node_bot,node_paths,node_herald,node_cinematic_client,node_runtime_state toneAmber
class node_dfu_mods,node_camera_mod,node_music_mod,node_map_logger toneRose
class node_bluesky,node_viewers,node_twitch,node_game_process,node_obs,node_bluesky_service toneIndigo
```

## Components

### Control Interfaces

- [Dev control page](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/templates/dev_control.html): `daggerwalk/templates/dev_control.html`
- [Dev HTTP server](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/dev_server.py): `daggerwalk/dev_server.py`
- [Supervisor](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/supervisor.py): `daggerwalk/supervisor.py`

### Bot Runtime

- [Command and session bot](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/twitch_bot.py): `daggerwalk/twitch_bot.py`
- [Runtime paths](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/paths.py): `daggerwalk/paths.py`
- [Milestone formatting](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/herald.py): `daggerwalk/herald.py`
- [Camera control client](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/cinematic.py): `daggerwalk/cinematic.py`
- [Runtime state and logs](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/paths.py): `daggerwalk/paths.py`

### DFU Mods

- [Gameplay mods](https://github.com/kershner/daggerwalk/tree/master/mods/dfu): `mods/dfu`
- [Cinematic camera mod](https://github.com/kershner/daggerwalk/blob/master/mods/dfu/CinematicCamera.cs): `mods/dfu/CinematicCamera.cs`
- [Music changer](https://github.com/kershner/daggerwalk/blob/master/mods/dfu/MusicChanger.cs): `mods/dfu/MusicChanger.cs`
- [Map data logger](https://github.com/kershner/daggerwalk/blob/master/mods/dfu/MapDataLogger.cs): `mods/dfu/MapDataLogger.cs`

### Stream Publishing

- [Status and milestone posts](https://github.com/kershner/daggerwalk/blob/master/daggerwalk/bluesky.py): `daggerwalk/bluesky.py`

### Other components

- **Twitch chat**
- **Local control user**
- **Twitch platform**
- **Daggerfall Unity**
- **OBS stream**
- **Bluesky**

## Connections

- Twitch chat → Command and session bot: send commands (evidence: `README.md`)
- Command and session bot → Twitch platform: connects to (evidence: `README.md`)
- Command and session bot → Daggerfall Unity: automates gameplay (evidence: `README.md`)
- Local control user → Dev control page: uses controls (evidence: `README.md`)
- Dev control page → Dev HTTP server: requests controls (evidence: `daggerwalk/dev_server.py`)
- Dev HTTP server → Command and session bot: dispatches commands (evidence: `daggerwalk/dev_server.py`)
- Command and session bot → Dev HTTP server: sends feedback (evidence: `daggerwalk/dev_server.py`)
- Supervisor → Daggerfall Unity: starts and stages (evidence: `daggerwalk/supervisor.py`)
- Supervisor → Command and session bot: launches or recovers (evidence: `daggerwalk/supervisor.py`)
- Supervisor → Dev HTTP server: launches dev mode (evidence: `daggerwalk/supervisor.py`)
- Command and session bot → Runtime paths: uses shared paths (evidence: `daggerwalk/twitch_bot.py`)
- Runtime paths → Runtime state and logs: defines locations (evidence: `daggerwalk/paths.py`)
- Command and session bot → Milestone formatting: formats milestones (evidence: `daggerwalk/twitch_bot.py`)
- Status and milestone posts → Milestone formatting: formats announcements (evidence: `daggerwalk/bluesky.py`)
- Command and session bot → Camera control client: requests camera state (evidence: `daggerwalk/twitch_bot.py`)
- Camera control client → Cinematic camera mod: exchanges status requests (evidence: `daggerwalk/cinematic.py`)
- Cinematic camera mod → Daggerfall Unity: controls camera (evidence: `mods/dfu/CinematicCamera.cs`)
- Music changer → Daggerfall Unity: changes music (evidence: `mods/dfu/MusicChanger.cs`)
- Map data logger → Daggerfall Unity: logs map data (evidence: `README.md`)
- Gameplay mods → Daggerfall Unity: adds gameplay features (evidence: `README.md`)
- Command and session bot → OBS stream: updates stream
- Command and session bot → Status and milestone posts: publishes updates (evidence: `daggerwalk/twitch_bot.py`)
- Status and milestone posts → Bluesky: posts status (evidence: `daggerwalk/bluesky.py`)
