# justsamyog/betterkeys architecture

> Architecture diagram of the GitHub repository justsamyog/betterkeys, 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/justsamyog/betterkeys
- Repository: https://github.com/justsamyog/betterkeys

## Overview

Better Keys is a Windows desktop sound-feedback app. Global keyboard and mouse events are captured and debounced, mapped through the active soundpack, then played by the audio engine; the tray UI manages packs, settings, and sound controls. Users can also import packs and edit per-key mappings. Edges are limited to calls shown in excerpts, SOURCE INDEX references, or README statements; unsampled implementation details are not asserted.

Main entry points: [`src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java`](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java) (Tray and Settings), [`src/main/java/com/justsamyog/betterkeys/ui/SoundpackEditorDialog.java`](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/SoundpackEditorDialog.java) (Pack Import Editor), [`src/main/java/com/justsamyog/betterkeys/ui/KeyMapperDialog.java`](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/KeyMapperDialog.java) (Key Sound Mapper), [`src/main/java/com/justsamyog/betterkeys/model/SoundpackManager.java`](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/model/SoundpackManager.java) (Pack Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Startup and Controls"]
  node_main["Application Entry<br/>[Main.java]"]
  node_config["App Configuration<br/>[AppConfig.java]"]
end

subgraph group_input["Global Input"]
  node_inputlistener["Global Input Hook"]
end

subgraph group_packs["Soundpacks"]
  node_manager["Pack Manager"]
  node_pack["Pack Model<br/>[Soundpack.java]"]
  node_converter["Legacy Pack Converter<br/>[PackConverter.java]"]
  node_packfiles[("Pack Files")]
end

subgraph group_audio["Audio Playback"]
  node_audioengine["Audio Engine<br/>[AudioEngine.java]"]
  node_wavgen["Default WAV Synthesis<br/>[WavGenerator.java]"]
end

subgraph group_interface["Desktop Interface"]
  node_tray["Tray and Settings<br/>[TrayApp.java]"]
  node_editor["Pack Import Editor"]
  node_mapper["Key Sound Mapper"]
  node_keyboardview["Keyboard View<br/>[KeyboardPanel.java]"]
  node_icons["Icon Rendering<br/>[IconLoader.java]"]
  node_gradient["Gradient Panel<br/>[GradientPanel.java]"]
  node_glass["Glass Panel<br/>[GlassPanel.java]"]
end

node_user(("User"))
node_osinput(("Keyboard and Mouse"))
node_audioout(("Audio Output"))

node_user -->|"launches"| node_main
node_main -->|"starts"| node_tray
node_tray -->|"loads and saves"| node_config
node_tray -->|"manages packs"| node_manager
node_tray -->|"configures"| node_inputlistener
node_tray -->|"controls playback"| node_audioengine
node_osinput -->|"sends events"| node_inputlistener
node_inputlistener -->|"plays mapped sounds"| node_audioengine
node_inputlistener -->|"selects variants"| node_pack
node_manager -->|"reads packs"| node_packfiles
node_manager -->|"creates models"| node_pack
node_manager -->|"converts legacy packs"| node_converter
node_user -->|"imports packs"| node_editor
node_editor -->|"uses pack manager"| node_manager
node_user -->|"edits key mappings"| node_mapper
node_mapper -->|"displays keyboard"| node_keyboardview
node_mapper -->|"updates mappings"| node_pack
node_mapper -->|"uses pack manager"| node_manager
node_audioengine -->|"plays samples"| node_audioout
node_audioengine -->|"decodes generated WAV"| node_wavgen
node_tray -->|"opens editor"| node_editor
node_tray -->|"opens mapper"| node_mapper
node_tray -->|"renders icons"| node_icons
node_editor -->|"renders icons"| node_icons
node_editor -->|"uses panel"| node_gradient
node_editor -->|"uses panel"| node_glass
node_mapper -->|"uses panel"| node_gradient

click node_main "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/Main.java"
click node_tray "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java"
click node_config "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/config/AppConfig.java"
click node_inputlistener "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/input/GlobalInputListener.java"
click node_manager "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/model/SoundpackManager.java"
click node_pack "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/model/Soundpack.java"
click node_converter "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/model/PackConverter.java"
click node_packfiles "https://github.com/justsamyog/betterkeys/tree/main/src/main/resources/soundpacks"
click node_editor "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/SoundpackEditorDialog.java"
click node_mapper "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/KeyMapperDialog.java"
click node_keyboardview "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/KeyboardPanel.java"
click node_audioengine "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/audio/AudioEngine.java"
click node_wavgen "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/audio/WavGenerator.java"
click node_icons "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/IconLoader.java"
click node_gradient "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/GradientPanel.java"
click node_glass "https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/GlassPanel.java"

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_main,node_config,node_user toneBlue
class node_inputlistener toneAmber
class node_manager,node_pack,node_converter,node_packfiles toneMint
class node_audioengine,node_wavgen toneRose
class node_tray,node_editor,node_mapper,node_keyboardview,node_icons,node_gradient,node_glass,node_osinput,node_audioout toneIndigo
```

## Components

### Startup and Controls

- [Application Entry](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/Main.java): `src/main/java/com/justsamyog/betterkeys/Main.java`
- [App Configuration](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/config/AppConfig.java): `src/main/java/com/justsamyog/betterkeys/config/AppConfig.java`

### Global Input

- [Global Input Hook](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/input/GlobalInputListener.java): `src/main/java/com/justsamyog/betterkeys/input/GlobalInputListener.java`

### Soundpacks

- [Pack Manager](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/model/SoundpackManager.java): `src/main/java/com/justsamyog/betterkeys/model/SoundpackManager.java`
- [Pack Model](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/model/Soundpack.java): `src/main/java/com/justsamyog/betterkeys/model/Soundpack.java`
- [Legacy Pack Converter](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/model/PackConverter.java): `src/main/java/com/justsamyog/betterkeys/model/PackConverter.java`
- [Pack Files](https://github.com/justsamyog/betterkeys/tree/main/src/main/resources/soundpacks): `src/main/resources/soundpacks`

### Audio Playback

- [Audio Engine](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/audio/AudioEngine.java): `src/main/java/com/justsamyog/betterkeys/audio/AudioEngine.java`
- [Default WAV Synthesis](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/audio/WavGenerator.java): `src/main/java/com/justsamyog/betterkeys/audio/WavGenerator.java`

### Desktop Interface

- [Tray and Settings](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java): `src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java`
- [Pack Import Editor](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/SoundpackEditorDialog.java): `src/main/java/com/justsamyog/betterkeys/ui/SoundpackEditorDialog.java`
- [Key Sound Mapper](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/KeyMapperDialog.java): `src/main/java/com/justsamyog/betterkeys/ui/KeyMapperDialog.java`
- [Keyboard View](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/KeyboardPanel.java): `src/main/java/com/justsamyog/betterkeys/ui/KeyboardPanel.java`
- [Icon Rendering](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/IconLoader.java): `src/main/java/com/justsamyog/betterkeys/ui/IconLoader.java`
- [Gradient Panel](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/GradientPanel.java): `src/main/java/com/justsamyog/betterkeys/ui/GradientPanel.java`
- [Glass Panel](https://github.com/justsamyog/betterkeys/blob/main/src/main/java/com/justsamyog/betterkeys/ui/GlassPanel.java): `src/main/java/com/justsamyog/betterkeys/ui/GlassPanel.java`

### Other components

- **User**
- **Keyboard and Mouse**
- **Audio Output**

## Connections

- User → Application Entry: launches (evidence: `README.md`)
- Application Entry → Tray and Settings: starts (evidence: `src/main/java/com/justsamyog/betterkeys/Main.java`)
- Tray and Settings → App Configuration: loads and saves (evidence: `src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java`)
- Tray and Settings → Pack Manager: manages packs (evidence: `src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java`)
- Tray and Settings → Global Input Hook: configures (evidence: `src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java`)
- Tray and Settings → Audio Engine: controls playback (evidence: `src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java`)
- Keyboard and Mouse → Global Input Hook: sends events (evidence: `src/main/java/com/justsamyog/betterkeys/input/GlobalInputListener.java`)
- Global Input Hook → Audio Engine: plays mapped sounds (evidence: `src/main/java/com/justsamyog/betterkeys/input/GlobalInputListener.java`)
- Global Input Hook → Pack Model: selects variants (evidence: `src/main/java/com/justsamyog/betterkeys/input/GlobalInputListener.java`)
- Pack Manager → Pack Files: reads packs (evidence: `src/main/java/com/justsamyog/betterkeys/model/SoundpackManager.java`)
- Pack Manager → Pack Model: creates models (evidence: `src/main/java/com/justsamyog/betterkeys/model/SoundpackManager.java`)
- Pack Manager → Legacy Pack Converter: converts legacy packs (evidence: `src/main/java/com/justsamyog/betterkeys/model/SoundpackManager.java`)
- User → Pack Import Editor: imports packs (evidence: `README.md`)
- Pack Import Editor → Pack Manager: uses pack manager (evidence: `src/main/java/com/justsamyog/betterkeys/ui/SoundpackEditorDialog.java`)
- User → Key Sound Mapper: edits key mappings (evidence: `README.md`)
- Key Sound Mapper → Keyboard View: displays keyboard (evidence: `src/main/java/com/justsamyog/betterkeys/ui/KeyMapperDialog.java`)
- Key Sound Mapper → Pack Model: updates mappings (evidence: `src/main/java/com/justsamyog/betterkeys/ui/KeyMapperDialog.java`)
- Key Sound Mapper → Pack Manager: uses pack manager (evidence: `src/main/java/com/justsamyog/betterkeys/ui/KeyMapperDialog.java`)
- Audio Engine → Audio Output: plays samples (evidence: `src/main/java/com/justsamyog/betterkeys/audio/AudioEngine.java`)
- Audio Engine → Default WAV Synthesis: decodes generated WAV (evidence: `src/main/java/com/justsamyog/betterkeys/audio/AudioEngine.java`)
- Tray and Settings → Pack Import Editor: opens editor (evidence: `src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java`)
- Tray and Settings → Key Sound Mapper: opens mapper (evidence: `src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java`)
- Tray and Settings → Icon Rendering: renders icons (evidence: `src/main/java/com/justsamyog/betterkeys/ui/TrayApp.java`)
- Pack Import Editor → Icon Rendering: renders icons (evidence: `src/main/java/com/justsamyog/betterkeys/ui/SoundpackEditorDialog.java`)
- Pack Import Editor → Gradient Panel: uses panel (evidence: `src/main/java/com/justsamyog/betterkeys/ui/SoundpackEditorDialog.java`)
- Pack Import Editor → Glass Panel: uses panel (evidence: `src/main/java/com/justsamyog/betterkeys/ui/SoundpackEditorDialog.java`)
- Key Sound Mapper → Gradient Panel: uses panel (evidence: `src/main/java/com/justsamyog/betterkeys/ui/KeyMapperDialog.java`)
