# dccif/keysteer architecture

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

- Interactive diagram: https://gitdiagram.com/dccif/keysteer
- Repository: https://github.com/dccif/keysteer

## Overview

KeySteer is a native keyboard-driven mouse and window-control application. Its primary workflow is keyboard input → binding and mode handling → commands executed through a platform backend → visible overlay feedback. The graph also preserves the documented window-layout, tabs, presets, UI Hint, audio, and configuration capabilities. Source excerpts confirm the API boundary, input routing, presentation composition, and parts of window-worker behavior; some subsystem connections are based on README capabilities and the repository tree, so uncertain wiring is omitted.

Main entry points: [`src/app/runtime/commands.rs`](https://github.com/dccif/keysteer/blob/main/src/app/runtime/commands.rs) (Command handling), [`src/app/mode_catalog.rs`](https://github.com/dccif/keysteer/blob/main/src/app/mode_catalog.rs) (Mode catalog), [`src/platform/mod.rs`](https://github.com/dccif/keysteer/blob/main/src/platform/mod.rs) (Platform backend), [`src/modes/window/mode.rs`](https://github.com/dccif/keysteer/blob/main/src/modes/window/mode.rs) (Window modes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_bootstrap["Startup<br/>[bootstrap.rs]"]
  node_router["Binding router<br/>[input_router.rs]"]
  node_runtime_plan["Runtime dispatch<br/>[plan.rs]"]
  node_mode_catalog["Mode catalog<br/>[mode_catalog.rs]"]
  node_commands["Command handling<br/>[commands.rs]"]
  node_backend_api["Backend API<br/>[backend.rs]"]
end

subgraph group_modes["Interaction modes"]
  node_normal["Normal mode<br/>[normal.rs]"]
  node_grid["Grid modes<br/>[grid.rs]"]
  node_recursive["Recursive Grid<br/>[recursive_grid.rs]"]
  node_hint["UI Hint<br/>[mod.rs]"]
end

subgraph group_windows["Window control"]
  node_window_mode["Window modes<br/>[mode.rs]"]
  node_window_worker["Window worker<br/>[worker.rs]"]
  node_presets["Layout presets<br/>[preset_store.rs]"]
  node_window_layout["Window layouts<br/>[window_layout.rs]"]
end

subgraph group_platform["Platform services"]
  node_input["Native input<br/>[mod.rs]"]
  node_backend_impl["Platform backend<br/>[mod.rs]"]
  node_scan["UI scanning"]
  node_window_native["Native windows<br/>[window_manager.rs]"]
  node_window_native_mac["macOS windows<br/>[window_manager.rs]"]
  node_audio["Audio service<br/>[audio_worker.rs]"]
  node_overlay["Native overlay<br/>[overlay.rs]"]
end

subgraph group_configuration["Configuration and presentation"]
  node_configuration["Config loading<br/>[store.rs]"]
  node_config_model["Config model<br/>[mod.rs]"]
  node_composer["Overlay composer<br/>[mod.rs]"]
end

node_user(("Keyboard user"))

node_user -->|"presses keys"| node_input
node_bootstrap -->|"loads settings"| node_configuration
node_configuration -->|"parses TOML"| node_config_model
node_bootstrap -->|"creates backend"| node_backend_impl
node_input -->|"delivers events"| node_router
node_router -->|"matches bindings"| node_runtime_plan
node_runtime_plan -->|"dispatches modes"| node_mode_catalog
node_mode_catalog -->|"selects mode"| node_normal
node_mode_catalog -->|"selects mode"| node_grid
node_mode_catalog -->|"selects mode"| node_recursive
node_mode_catalog -->|"selects mode"| node_hint
node_mode_catalog -->|"selects mode"| node_window_mode
node_normal -->|"returns commands"| node_commands
node_grid -->|"returns commands"| node_commands
node_recursive -->|"returns commands"| node_commands
node_hint -->|"returns commands"| node_commands
node_window_mode -->|"returns commands"| node_commands
node_commands -->|"executes commands"| node_backend_api
node_backend_impl -->|"implements"| node_backend_api
node_backend_impl -->|"scans UI"| node_scan
node_backend_impl -->|"handles audio"| node_audio
node_commands -->|"submits operations"| node_window_worker
node_window_worker -->|"runs operations"| node_window_native
node_window_worker -->|"runs operations"| node_window_native_mac
node_window_mode -->|"requests layouts"| node_window_layout
node_window_mode -->|"uses presets"| node_presets
node_commands -->|"requests feedback"| node_composer
node_composer -->|"composes scenes"| node_overlay
node_backend_impl -->|"renders scenes"| node_overlay

click node_bootstrap "https://github.com/dccif/keysteer/blob/main/src/app/bootstrap.rs"
click node_configuration "https://github.com/dccif/keysteer/blob/main/src/config/store.rs"
click node_config_model "https://github.com/dccif/keysteer/blob/main/src/config/mod.rs"
click node_input "https://github.com/dccif/keysteer/blob/main/src/platform/mod.rs"
click node_router "https://github.com/dccif/keysteer/blob/main/src/app/runtime/input_router.rs"
click node_runtime_plan "https://github.com/dccif/keysteer/blob/main/src/app/runtime/plan.rs"
click node_mode_catalog "https://github.com/dccif/keysteer/blob/main/src/app/mode_catalog.rs"
click node_normal "https://github.com/dccif/keysteer/blob/main/src/modes/normal.rs"
click node_grid "https://github.com/dccif/keysteer/blob/main/src/modes/grid.rs"
click node_recursive "https://github.com/dccif/keysteer/blob/main/src/modes/recursive_grid.rs"
click node_hint "https://github.com/dccif/keysteer/blob/main/src/modes/hint/mod.rs"
click node_window_mode "https://github.com/dccif/keysteer/blob/main/src/modes/window/mode.rs"
click node_commands "https://github.com/dccif/keysteer/blob/main/src/app/runtime/commands.rs"
click node_backend_api "https://github.com/dccif/keysteer/blob/main/src/api/backend.rs"
click node_backend_impl "https://github.com/dccif/keysteer/blob/main/src/platform/mod.rs"
click node_scan "https://github.com/dccif/keysteer/blob/main/src/platform/common/scan_accumulator.rs"
click node_window_worker "https://github.com/dccif/keysteer/blob/main/src/platform/common/window_session/worker.rs"
click node_window_native "https://github.com/dccif/keysteer/blob/main/src/platform/windows/window_manager.rs"
click node_window_native_mac "https://github.com/dccif/keysteer/blob/main/src/platform/macos/accessibility/window_manager.rs"
click node_presets "https://github.com/dccif/keysteer/blob/main/src/app/preset_store.rs"
click node_audio "https://github.com/dccif/keysteer/blob/main/src/platform/common/audio_worker.rs"
click node_composer "https://github.com/dccif/keysteer/blob/main/src/presentation/mod.rs"
click node_overlay "https://github.com/dccif/keysteer/blob/main/src/api/overlay.rs"
click node_window_layout "https://github.com/dccif/keysteer/blob/main/src/api/window_layout.rs"

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_bootstrap,node_router,node_runtime_plan,node_mode_catalog,node_commands,node_backend_api,node_user toneBlue
class node_normal,node_grid,node_recursive,node_hint toneAmber
class node_window_mode,node_window_worker,node_presets,node_window_layout toneMint
class node_input,node_backend_impl,node_scan,node_window_native,node_window_native_mac,node_audio,node_overlay toneRose
class node_configuration,node_config_model,node_composer toneIndigo
```

## Components

### Application runtime

- [Startup](https://github.com/dccif/keysteer/blob/main/src/app/bootstrap.rs): `src/app/bootstrap.rs`
- [Binding router](https://github.com/dccif/keysteer/blob/main/src/app/runtime/input_router.rs): `src/app/runtime/input_router.rs`
- [Runtime dispatch](https://github.com/dccif/keysteer/blob/main/src/app/runtime/plan.rs): `src/app/runtime/plan.rs`
- [Mode catalog](https://github.com/dccif/keysteer/blob/main/src/app/mode_catalog.rs): `src/app/mode_catalog.rs`
- [Command handling](https://github.com/dccif/keysteer/blob/main/src/app/runtime/commands.rs): `src/app/runtime/commands.rs`
- [Backend API](https://github.com/dccif/keysteer/blob/main/src/api/backend.rs): `src/api/backend.rs`

### Interaction modes

- [Normal mode](https://github.com/dccif/keysteer/blob/main/src/modes/normal.rs): `src/modes/normal.rs`
- [Grid modes](https://github.com/dccif/keysteer/blob/main/src/modes/grid.rs): `src/modes/grid.rs`
- [Recursive Grid](https://github.com/dccif/keysteer/blob/main/src/modes/recursive_grid.rs): `src/modes/recursive_grid.rs`
- [UI Hint](https://github.com/dccif/keysteer/blob/main/src/modes/hint/mod.rs): `src/modes/hint/mod.rs`

### Window control

- [Window modes](https://github.com/dccif/keysteer/blob/main/src/modes/window/mode.rs): `src/modes/window/mode.rs`
- [Window worker](https://github.com/dccif/keysteer/blob/main/src/platform/common/window_session/worker.rs): `src/platform/common/window_session/worker.rs`
- [Layout presets](https://github.com/dccif/keysteer/blob/main/src/app/preset_store.rs): `src/app/preset_store.rs`
- [Window layouts](https://github.com/dccif/keysteer/blob/main/src/api/window_layout.rs): `src/api/window_layout.rs`

### Platform services

- [Native input](https://github.com/dccif/keysteer/blob/main/src/platform/mod.rs): `src/platform/mod.rs`
- [Platform backend](https://github.com/dccif/keysteer/blob/main/src/platform/mod.rs): `src/platform/mod.rs`
- [UI scanning](https://github.com/dccif/keysteer/blob/main/src/platform/common/scan_accumulator.rs): `src/platform/common/scan_accumulator.rs`
- [Native windows](https://github.com/dccif/keysteer/blob/main/src/platform/windows/window_manager.rs): `src/platform/windows/window_manager.rs`
- [macOS windows](https://github.com/dccif/keysteer/blob/main/src/platform/macos/accessibility/window_manager.rs): `src/platform/macos/accessibility/window_manager.rs`
- [Audio service](https://github.com/dccif/keysteer/blob/main/src/platform/common/audio_worker.rs): `src/platform/common/audio_worker.rs`
- [Native overlay](https://github.com/dccif/keysteer/blob/main/src/api/overlay.rs): `src/api/overlay.rs`

### Configuration and presentation

- [Config loading](https://github.com/dccif/keysteer/blob/main/src/config/store.rs): `src/config/store.rs`
- [Config model](https://github.com/dccif/keysteer/blob/main/src/config/mod.rs): `src/config/mod.rs`
- [Overlay composer](https://github.com/dccif/keysteer/blob/main/src/presentation/mod.rs): `src/presentation/mod.rs`

### Other components

- **Keyboard user**

## Connections

- Keyboard user → Native input: presses keys
- Startup → Config loading: loads settings
- Config loading → Config model: parses TOML
- Startup → Platform backend: creates backend
- Native input → Binding router: delivers events
- Binding router → Runtime dispatch: matches bindings
- Runtime dispatch → Mode catalog: dispatches modes
- Mode catalog → Normal mode: selects mode
- Mode catalog → Grid modes: selects mode
- Mode catalog → Recursive Grid: selects mode
- Mode catalog → UI Hint: selects mode
- Mode catalog → Window modes: selects mode
- Normal mode → Command handling: returns commands
- Grid modes → Command handling: returns commands
- Recursive Grid → Command handling: returns commands
- UI Hint → Command handling: returns commands
- Window modes → Command handling: returns commands
- Command handling → Backend API: executes commands
- Platform backend → Backend API: implements
- Platform backend → UI scanning: scans UI
- Platform backend → Audio service: handles audio
- Command handling → Window worker: submits operations
- Window worker → Native windows: runs operations
- Window worker → macOS windows: runs operations
- Window modes → Window layouts: requests layouts
- Window modes → Layout presets: uses presets
- Command handling → Overlay composer: requests feedback
- Overlay composer → Native overlay: composes scenes
- Platform backend → Native overlay: renders scenes