# journeydocker/twitchdropsminer architecture

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

## Overview

Twitch Drops Miner is a desktop application that advances timed Twitch drops without downloading stream media. The user logs in, selects prioritized games, and starts processing; the client discovers eligible campaigns and channels, tracks stream status, periodically sends watch requests, and claims completed drops. The GUI also exposes inventory, channel, progress, and settings views, with optional notifications. The README documents capabilities such as sharded websocket tracking and campaign validation; excerpts show the client, channel, inventory, and websocket roles, but not all of their internal wiring.

Main entry points: [`twitch.py`](https://github.com/journeydocker/twitchdropsminer/blob/main/twitch.py) (Twitch client), [`gui.py`](https://github.com/journeydocker/twitchdropsminer/blob/main/gui.py) (Desktop GUI), [`cache.py`](https://github.com/journeydocker/twitchdropsminer/blob/main/cache.py) (Image cache), [`notifications.py`](https://github.com/journeydocker/twitchdropsminer/blob/main/notifications.py) (Drop notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_gui["Desktop GUI<br/>[gui.py]"]
  node_main["Application entry<br/>[main.py]"]
end

subgraph group_mining["Drop mining"]
  node_inventory["Campaign inventory<br/>[inventory.py]"]
  node_channel["Channel and stream<br/>[channel.py]"]
  node_drops["Timed drops<br/>[inventory.py]"]
end

subgraph group_connectivity["Twitch connectivity"]
  node_twitch["Twitch client<br/>[twitch.py]"]
  node_websocket["Websocket pool<br/>[websocket.py]"]
end

subgraph group_support["Settings and support"]
  node_settings["Settings<br/>[settings.py]"]
  node_settingsfile["Settings file"]
  node_notifications["Drop notifications<br/>[notifications.py]"]
  node_cache["Image cache<br/>[cache.py]"]
  node_cachefiles["Cached images"]
  node_translations["Translations<br/>[translate.py]"]
end

node_user(("User"))
node_twitchapi["Twitch services"]
node_notificationservice["Notification services"]

node_user -->|"configures and starts"| node_gui
node_main -->|"runs client"| node_twitch
node_main -->|"starts interface"| node_gui
node_gui -->|"controls and displays"| node_twitch
node_gui -->|"edits preferences"| node_settings
node_settings -->|"loads and saves"| node_settingsfile
node_twitch -->|"requests account and campaigns"| node_twitchapi
node_twitch -->|"builds campaign state"| node_inventory
node_twitch -->|"selects and watches"| node_channel
node_channel -->|"requests stream metadata"| node_twitchapi
node_twitch -->|"manages subscriptions"| node_websocket
node_websocket -->|"dispatches stream events"| node_twitch
node_twitch -->|"tracks mining progress"| node_drops
node_drops -->|"claims completed drops"| node_twitchapi
node_twitch -.->|"reports claimed drops"| node_notifications
node_gui -->|"tests notification settings"| node_notifications
node_notifications -.->|"sends alerts"| node_notificationservice
node_gui -->|"displays images"| node_cache
node_cache -->|"fetches images"| node_twitchapi
node_cache -->|"reads and writes"| node_cachefiles
node_gui -->|"loads interface text"| node_translations

click node_gui "https://github.com/journeydocker/twitchdropsminer/blob/main/gui.py"
click node_main "https://github.com/journeydocker/twitchdropsminer/blob/main/main.py"
click node_settings "https://github.com/journeydocker/twitchdropsminer/blob/main/settings.py"
click node_twitch "https://github.com/journeydocker/twitchdropsminer/blob/main/twitch.py"
click node_inventory "https://github.com/journeydocker/twitchdropsminer/blob/main/inventory.py"
click node_channel "https://github.com/journeydocker/twitchdropsminer/blob/main/channel.py"
click node_websocket "https://github.com/journeydocker/twitchdropsminer/blob/main/websocket.py"
click node_drops "https://github.com/journeydocker/twitchdropsminer/blob/main/inventory.py"
click node_notifications "https://github.com/journeydocker/twitchdropsminer/blob/main/notifications.py"
click node_cache "https://github.com/journeydocker/twitchdropsminer/blob/main/cache.py"
click node_translations "https://github.com/journeydocker/twitchdropsminer/blob/main/translate.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_gui,node_main,node_user toneBlue
class node_inventory,node_channel,node_drops toneAmber
class node_twitch,node_websocket toneMint
class node_settings,node_settingsfile,node_notifications,node_cache,node_cachefiles,node_translations toneRose
class node_twitchapi,node_notificationservice toneIndigo
```

## Components

### User interface

- [Desktop GUI](https://github.com/journeydocker/twitchdropsminer/blob/main/gui.py): `gui.py`
- [Application entry](https://github.com/journeydocker/twitchdropsminer/blob/main/main.py): `main.py`

### Drop mining

- [Campaign inventory](https://github.com/journeydocker/twitchdropsminer/blob/main/inventory.py): `inventory.py`
- [Channel and stream](https://github.com/journeydocker/twitchdropsminer/blob/main/channel.py): `channel.py`
- [Timed drops](https://github.com/journeydocker/twitchdropsminer/blob/main/inventory.py): `inventory.py`

### Twitch connectivity

- [Twitch client](https://github.com/journeydocker/twitchdropsminer/blob/main/twitch.py): `twitch.py`
- [Websocket pool](https://github.com/journeydocker/twitchdropsminer/blob/main/websocket.py): `websocket.py`

### Settings and support

- [Settings](https://github.com/journeydocker/twitchdropsminer/blob/main/settings.py): `settings.py`
- **Settings file**
- [Drop notifications](https://github.com/journeydocker/twitchdropsminer/blob/main/notifications.py): `notifications.py`
- [Image cache](https://github.com/journeydocker/twitchdropsminer/blob/main/cache.py): `cache.py`
- **Cached images**
- [Translations](https://github.com/journeydocker/twitchdropsminer/blob/main/translate.py): `translate.py`

### Other components

- **User**
- **Twitch services**
- **Notification services**

## Connections

- User → Desktop GUI: configures and starts
- Application entry → Twitch client: runs client
- Application entry → Desktop GUI: starts interface
- Desktop GUI → Twitch client: controls and displays
- Desktop GUI → Settings: edits preferences
- Settings → Settings file: loads and saves
- Twitch client → Twitch services: requests account and campaigns
- Twitch client → Campaign inventory: builds campaign state
- Twitch client → Channel and stream: selects and watches
- Channel and stream → Twitch services: requests stream metadata
- Twitch client → Websocket pool: manages subscriptions
- Websocket pool → Twitch client: dispatches stream events
- Twitch client → Timed drops: tracks mining progress
- Timed drops → Twitch services: claims completed drops
- Twitch client → Drop notifications: reports claimed drops
- Desktop GUI → Drop notifications: tests notification settings
- Drop notifications → Notification services: sends alerts
- Desktop GUI → Image cache: displays images
- Image cache → Twitch services: fetches images
- Image cache → Cached images: reads and writes
- Desktop GUI → Translations: loads interface text