Majjo Duran
9f2f62e2f2
- Added .github and .vscode to .gitignore - Created Docs folder with comprehensive documentation - Added CODEBASE_ANALYSIS.md: Detailed analysis of existing bot architecture - Added PROJECT_ROADMAP.md: Project goals and development roadmap - Project goal: Transform Channel Points Miner into Twitch Drops Miner
360 lines
12 KiB
Markdown
360 lines
12 KiB
Markdown
# 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:**
|
||
```python
|
||
- 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:**
|
||
```python
|
||
- 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:**
|
||
```python
|
||
- 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:**
|
||
```python
|
||
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:**
|
||
```python
|
||
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*
|