Twitch-Drops-Miner/Docs/CODEBASE_ANALYSIS.md

Twitch Channel Points Miner v2 - Codebase Analysis

Date: February 17, 2026
Purpose: Understanding the existing codebase before converting to a Twitch Drops-focused bot
Original Project: https://github.com/rdavydov/Twitch-Channel-Points-Miner-v2

---

📋 Executive Summary

This bot is a Python-based application designed to automatically watch Twitch streams to earn channel points. It includes existing drops functionality that we can leverage and expand upon for our Twitch Drops-focused implementation.

Key Finding: The bot already has a solid drops infrastructure including:

• Drop claiming mechanisms
• Campaign tracking
• Inventory synchronization
• Drop progress monitoring

---

🏗️ Architecture Overview

Core Components

1. TwitchChannelPointsMiner (Main Entry Point)

• Location: TwitchChannelPointsMiner/TwitchChannelPointsMiner.py
• Purpose: Main orchestrator class that manages the entire bot lifecycle
• Key Features:
  • Handles authentication via Twitch class
  • Manages multiple streamers simultaneously
  • Coordinates WebSocket connections for real-time updates
  • Implements priority system for streamer selection
  • Spawns threads for monitoring and synchronization

Important Parameters:

- username: Twitch account username
- password: Optional password (prompts if not provided)
- claim_drops_startup: Auto-claim all drops on startup (Boolean)
- priority: List defining watch priority [STREAK, DROPS, ORDER, etc.]
- enable_analytics: Track statistics (Boolean)
- logger_settings: Logging configuration
- streamer_settings: Default settings for all streamers

2. Twitch Class (API Handler)

• Location: TwitchChannelPointsMiner/classes/Twitch.py
• Purpose: Handles all Twitch API interactions via GraphQL
• Key Methods for Drops:
  • claim_drop(drop) - Claims a single drop
  • claim_all_drops_from_inventory() - Claims all available drops from inventory
  • sync_campaigns(streamers, chunk_size) - Synchronizes campaign data every 30 minutes
  • __get_inventory() - Fetches user's drops inventory
  • __get_drops_dashboard(status) - Gets active/expired campaigns
  • __get_campaigns_details(campaigns) - Gets detailed campaign information
  • __sync_campaigns(campaigns) - Updates campaign progress

3. Drop Entity

• Location: TwitchChannelPointsMiner/classes/entities/Drop.py
• Purpose: Represents a single drop reward
• Properties:

  - id: Unique drop identifier
  - name: Drop name
  - benefit: Reward description
  - minutes_required: Watch time needed
  - current_minutes_watched: Progress
  - percentage_progress: Completion percentage
  - is_claimable: Whether drop can be claimed
  - is_claimed: Whether drop has been claimed
  - drop_instance_id: Instance identifier for claiming
  

4. Campaign Entity

• Location: TwitchChannelPointsMiner/classes/entities/Campaign.py
• Purpose: Represents a Twitch Drops campaign
• Properties:

  - id: Campaign identifier
  - game: Associated game information
  - name: Campaign name
  - status: Campaign status (ACTIVE, EXPIRED, etc.)
  - drops: List of Drop objects
  - channels: Eligible channel IDs
  - start_at/end_at: Campaign timeframe
  

• Key Methods:
  • clear_drops() - Removes expired/claimed drops
  • sync_drops(drops, callback) - Updates drop progress

5. Priority System

• Location: TwitchChannelPointsMiner/classes/Settings.py
• Enum Values:

  Priority.STREAK      # Watch streak priority
  Priority.DROPS       # Drops collection priority
  Priority.ORDER       # Custom ordering
  Priority.SUBSCRIBED  # Subscribed channels first
  Priority.POINTS_ASCENDING / POINTS_DESCENDING
  

---

🔄 Workflow & Data Flow

Current Bot Flow:

1. Initialization

   • Authenticate with Twitch
   • Load streamer list
   • Configure logger and settings
   • Check for updates

2. Startup Phase

   • If claim_drops_startup=True, claim all available drops
   • Initialize WebSocket pool for real-time updates
   • Start analytics server (if enabled)

3. Main Loop

   • Streamer Selection: Choose streamer based on priority system

     • Priority.STREAK: Prioritize maintaining watch streaks
     • Priority.DROPS: Prioritize streamers with active drop campaigns
     • Priority.ORDER: Use custom ordering

   • Watching: Join stream via WebSocket, simulate viewing

   • Background Threads:

     • minute_watcher_thread: Tracks watch time, handles bonuses
     • sync_campaigns_thread: Syncs drops every 30 minutes

4. Drop Handling (Current Implementation)

   Every 30 minutes:
   └─ sync_campaigns()
      ├─ claim_all_drops_from_inventory()
      ├─ Fetch active campaigns from dashboard
      ├─ Update campaign/drop progress
      ├─ Check if drops are claimable
      └─ Auto-claim claimable drops
   

5. Events & Notifications

   • Events fired: Events.DROP_CLAIM, Events.DROP_STATUS
   • Notifications via: Discord, Telegram, Matrix, Pushover, Gotify, Webhook

---

📊 Key Files & Directory Structure

TwitchBot/
├── TwitchChannelPointsMiner/
│   ├── TwitchChannelPointsMiner.py      # Main orchestrator
│   ├── classes/
│   │   ├── Twitch.py                    # API handler
│   │   ├── TwitchLogin.py               # Authentication
│   │   ├── TwitchWebSocket.py           # WebSocket handling
│   │   ├── WebSocketsPool.py            # Socket pool manager
│   │   ├── Chat.py                      # Chat interaction
│   │   ├── Settings.py                  # Global settings & enums
│   │   ├── AnalyticsServer.py           # Flask analytics server
│   │   ├── entities/
│   │   │   ├── Drop.py                  # Drop model
│   │   │   ├── Campaign.py              # Campaign model
│   │   │   ├── Streamer.py              # Streamer model
│   │   │   ├── Stream.py                # Stream model
│   │   │   ├── Bet.py                   # Betting model
│   │   │   └── ...
│   │   └── [Notification classes]       # Discord, Telegram, etc.
│   ├── constants.py                     # API endpoints & constants
│   ├── logger.py                        # Logging configuration
│   └── utils.py                         # Helper functions
├── example.py                           # Configuration template
├── requirements.txt                     # Dependencies
└── Docs/                                # Documentation (new)

---

🎯 Current Drops Implementation Details

How Drops Currently Work:

1. Campaign Discovery:

   • Fetches active campaigns from Twitch Drops Dashboard
   • Filters campaigns by date range (start_at < now < end_at)
   • Associates campaigns with eligible streamers

2. Progress Tracking:

   • Watches are tracked via WebSocket "watching" messages
   • Progress updates come from inventory sync (every 30 min)
   • Drop progress calculated: currentMinutesWatched / minutesRequired

3. Claiming Logic:

   • Drop becomes claimable when:
     • currentMinutesWatched >= minutesRequired
     • hasPreconditionsMet == true
     • drop_instance_id is available
   • Claim via GraphQL mutation: DropsPage_ClaimDropRewards
   • Automatic retry with 5-10 second random delay

4. Per-Streamer Configuration:

   StreamerSettings(
       claim_drops=True,  # Enable drops for this streamer
       ...
   )
   

Current Limitations for Our Use Case:

1. Primary Focus: Channel points, not drops

   • Drops are secondary to point mining
   • Priority system favors streaks over drops
   • Limited drop-specific logging

2. Fixed Sync Interval: 30-minute campaign sync

   • Could miss time-sensitive drops
   • Not optimized for drop-focused workflow

3. Limited Drop Intelligence:

   • No prediction of drop completion times
   • No optimization for multi-campaign scenarios
   • No handling of channel-specific drop requirements

4. Streamer Selection:

   • Priority system doesn't optimize for drop efficiency
   • No automatic discovery of best streams for active campaigns

---

🔍 Dependencies Analysis

Core Dependencies:

requests              # HTTP requests
websocket-client      # WebSocket connections
pillow                # Image processing (for OCR?)
python-dateutil       # Date parsing
emoji                 # Emoji support
millify               # Number formatting
colorama              # Colored terminal output
flask                 # Analytics server
irc                   # IRC chat (minimal usage)
pandas                # Analytics data
pytz                  # Timezone handling
validators            # Input validation
pre-commit            # Development tool

All dependencies are standard and well-maintained.

---

🎨 Notification System

The bot supports multiple notification channels for events:

• Discord - Via webhook
• Telegram - Via bot API
• Matrix - Matrix protocol
• Pushover - Push notifications
• Gotify - Self-hosted notifications
• Webhook - Generic webhooks

Relevant Events for Drops:

• Events.DROP_CLAIM - Drop claimed
• Events.DROP_STATUS - Drop progress update

---

💡 Recommendations for Drops-Focused Bot

What to Keep:

✅ Drop & Campaign entity models (well-designed)
✅ Twitch API/GraphQL integration (solid)
✅ WebSocket infrastructure (essential)
✅ Notification system (useful for alerts)
✅ Logger system (comprehensive)
✅ Authentication mechanism (working)

What to Modify:

🔧 Priority system → Make drops the primary focus
🔧 Sync interval → Reduce to ~5-10 minutes for drops
🔧 Streamer selection → Algorithm optimized for drop campaigns
🔧 Progress tracking → More granular, per-campaign insights
🔧 Configuration → Simplify for drops-only use case

What to Remove/Deprecate:

❌ Betting system (not needed for drops)
❌ Channel points tracking (secondary concern)
❌ Community goals (not relevant)
❌ Watch streak priority (not needed)
❌ Analytics system (or simplify significantly)

New Features to Add:

➕ Campaign prioritization algorithm
➕ Automatic discovery of best streams per campaign
➕ Drop progress predictions & ETA
➕ Multi-account support for faster farming
➕ Campaign completion tracking
➕ Smart switching between campaigns
➕ Detailed drop statistics dashboard

---

🚀 Next Steps

1. Phase 1: Configuration & Setup

   • Create drops-focused default config
   • Update example.py for drops use case
   • Simplify unnecessary features

2. Phase 2: Core Logic Modifications

   • Implement drops-first priority system
   • Reduce campaign sync interval
   • Enhance drop progress logging

3. Phase 3: New Features

   • Campaign optimizer
   • Smart streamer selection
   • Drop ETA predictions

4. Phase 4: Testing & Documentation

   • Test with active campaigns
   • Document new usage patterns
   • Create user guide

---

📝 Technical Notes

GraphQL Operations Used:

• DropsPage_ClaimDropRewards - Claim drop
• Inventory - Get user inventory
• ViewerDropsDashboard - Get campaigns
• DropCampaignDetails - Get campaign details

WebSocket Topics:

• video-playback-by-id - Stream events
• predictions-channel-v1 - Predictions
• Drops progress updates come via API polling, not WebSocket

Authentication:

• Uses OAuth login flow
• Stores auth token and cookies
• Handles token refresh automatically

---

🎓 Conclusion

The codebase is well-structured and maintainable. The existing drops functionality provides a solid foundation. Our main task is to shift focus from channel points to drops, optimize the workflow, and add drop-specific enhancements.

Confidence Level: High - The codebase is ready for modification with minimal breaking changes needed.

---

Document created during initial codebase review - February 17, 2026