# rdavydov/twitch-channel-points-miner-v2 architecture

> Architecture diagram of the GitHub repository rdavydov/twitch-channel-points-miner-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rdavydov/twitch-channel-points-miner-v2
- Repository: https://github.com/rdavydov/twitch-channel-points-miner-v2

## Overview

##### Main system components
a. Entry-point script:
- run.py / example.py – instantiates TwitchChannelPointsMiner and kicks off mine() or analytics()
b. Core library (TwitchChannelPointsMiner package):
- Engine: orchestrates sessions, loops through streamers, applies priority and settings
- Event manager: reacts to “streamer online/offline,” bonus claim, drops, streaks, raids, predictions
- Entities & domain classes: Streamer, EventPrediction, BetSettings, CommunityGoal, Drop, Campaign, Message, etc.
- Connectors:
– TwitchLogin (HTTP login, cookies)
– TwitchWebSocket (IRC chat & PubSub for events)
– WebSocketsPool (shared socket handling)
- Notification adapters: Discord, Telegram, Matrix, Gotify, Pushover, Generic Webhook
c. Analytics web server:
- AnalyticsServer (Flask) reads JSON from analytics folder
- Static assets (assets/*.html, script.js, style.css) render point-trend charts
d. Infrastructure & storage:
- Local volumes: cookies/, logs/, analytics/
- Docker container (Dockerfile + docker-compose example)
- CI/CD workflows (.github/workflows)

##### External dependencies & integrations
- Twitch platform:
– HTTP API (login, fetch drops, moments)
– WebSocket/IRC for chat and PubSub topics (predictions, raids)
- Third-party notification services:
Discord webhook URL
Telegram Bot API
Matrix homeserver
Gotify endpoint
Pushover API
Generic Webhook endpoints

##### Relationships & data flows
a. run.py triggers the Engine → Core library
b. Engine uses TwitchLogin to authenticate → writes cookie to cookies/
c. Engine opens TwitchWebSocket → listens for channel-points events
d. Event manager applies settings (StreamerSettings, BetSettings) → executes actions via WebSocket or HTTP
e. Outcomes: points earned → logged by Logger → stored in logs/
f. If analytics enabled: Engine writes point events to analytics/*.json → AnalyticsServer reads them → serves charts via static assets
g. Notification adapters subscribe to Engine events → push messages to external services

##### Architectural patterns
- Modular library design: separation between core logic, domain entities, connectors, and adapters
- Plugin/adaptor pattern for notifications – easily extendable
- Priority-driven event loop (two concurrent streams max per Twitch limit)
- MVC-like pattern for analytics UI: Flask (“Controller”), analytics JSON (“Model”), assets+chart.js (“View”)

##### Diagramming conventions
– Ovals for entry-point/run.py and end-user
– Rectangles for modules/packages
– Core engine & entities (blue)
– External services & APIs (green)
– Storage volumes (orange)
– UI/web server (purple)

## Diagram (Mermaid)

```mermaid
flowchart TD
    A(("User")):::external
    B(["Entry-point: example.py"]):::entry
    A -->|runs| B

    subgraph "Core Library"
        C["Engine\nTwitchChannelPointsMiner"]:::core

        subgraph Connectors
            Conn1["TwitchLogin"]:::connector
            Conn2["TwitchWebSocket"]:::connector
            Conn3["WebSocketsPool"]:::connector
            Conn4["Twitch API Wrapper"]:::connector
        end

        subgraph "Event Manager & Chat"
            EM["EventManager"]:::core
            Chat["Chat Handler"]:::core
        end

        subgraph Entities
            E1["BetSettings"]:::entity
            E2["Campaign"]:::entity
            E3["CommunityGoal"]:::entity
            E4["Drop"]:::entity
            E5["EventPrediction"]:::entity
            E6["Message"]:::entity
            E7["PubsubTopic"]:::entity
            E8["Raid"]:::entity
            E9["Stream"]:::entity
            E10["Streamer"]:::entity
        end

        subgraph "Notification Adapters"
            NA1["Discord"]:::adapter
            NA2["Telegram"]:::adapter
            NA3["Matrix"]:::adapter
            NA4["Gotify"]:::adapter
            NA5["Pushover"]:::adapter
            NA6["Webhook"]:::adapter
        end

        Logger["Logger"]:::logger
        Settings["Settings"]:::core
        AnalyticsWriter["AnalyticsWriter"]:::core
    end

    B --> C
    C -->|uses| Conn1
    C -->|opens| Conn2
    C -->|shares| Conn3
    C -->|calls| Conn4

    Conn1 -->|HTTP| ExternalAPI["Twitch HTTP API"]:::external
    Conn2 -->|WebSocket/IRC| ExternalWS["Twitch Chat & PubSub"]:::external

    EM --> Chat
    EM -->|handles| E1 & E2 & E3 & E4 & E5 & E6 & E7 & E8 & E9 & E10
    EM -->|publishes| NA1
    EM -->|publishes| NA2
    EM -->|publishes| NA3
    EM -->|publishes| NA4
    EM -->|publishes| NA5
    EM -->|publishes| NA6

    C -->|executes| EM
    C -->|loads| Settings
    C -->|logs to| Logger
    Logger --> LogsCyl["logs/"]:::storage

    C -->|writes events| AnalyticsWriter
    AnalyticsWriter --> AnalyticsCyl["analytics/"]:::storage
    AnalyticsCyl --> AnalyticsServer["AnalyticsServer\n(Flask)"]:::ui
    AnalyticsServer --> Assets["Static Assets\n(chart UI)"]:::ui

    subgraph "Storage Volumes"
        CookiesCyl["cookies/"]:::storage
    end
    Conn1 -->|writes| CookiesCyl

    subgraph "Infrastructure & CI/CD"
        Docker["Docker Container"]:::infra
        CI["CI/CD Workflows"]:::infra
    end

    click B "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/example.py"
    click C "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/TwitchChannelPointsMiner.py"
    click Conn1 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/TwitchLogin.py"
    click Conn2 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/TwitchWebSocket.py"
    click Conn3 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/WebSocketsPool.py"
    click Conn4 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/Twitch.py"
    click Chat "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/Chat.py"
    click E1 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/Bet.py"
    click E2 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/Campaign.py"
    click E3 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/CommunityGoal.py"
    click E4 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/Drop.py"
    click E5 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/EventPrediction.py"
    click E6 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/Message.py"
    click E7 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/PubsubTopic.py"
    click E8 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/Raid.py"
    click E9 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/Stream.py"
    click E10 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/entities/Streamer.py"
    click NA1 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/Discord.py"
    click NA2 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/Telegram.py"
    click NA3 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/Matrix.py"
    click NA4 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/Gotify.py"
    click NA5 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/Pushover.py"
    click NA6 "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/Webhook.py"
    click Logger "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/logger.py"
    click Settings "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/Settings.py"
    click AnalyticsServer "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/TwitchChannelPointsMiner/classes/AnalyticsServer.py"
    click Assets "https://github.com/rdavydov/twitch-channel-points-miner-v2/blob/master/assets/charts.html"

    classDef core fill:#D6E9FE,stroke:#2B6CB0
    classDef connector fill:#EBF8FF,stroke:#2B6CB0
    classDef entity fill:#EBF8FF,stroke:#2B6CB0
    classDef adapter fill:#E6FFFA,stroke:#319795
    classDef logger fill:#EBF8FF,stroke:#2B6CB0
    classDef entry fill:#FFF5F5,stroke:#C53030
    classDef external fill:#DFF6DF,stroke:#2F855A
    classDef storage fill:#FDEFE0,stroke:#DD6B20
    classDef ui fill:#F3E8FF,stroke:#9F7AEA
    classDef infra fill:#EDF2F7,stroke:#A0AEC0
```
