DuckDice Bot is a professional automation toolkit for DuckDice.io with web (NiceGUI) and legacy desktop (Tkinter) interfaces. The primary interface is the NiceGUI web application (gui/app.py). Safety, clarity, and predictability are the highest priorities.
Version: 4.0.0 (NiceGUI Complete Edition)
Status: Production Ready ✅
Primary Entry:
python3 gui/app.py
or
./run_nicegui.sh
Safety first - User must always be in control
Predictability - No surprises, no hidden behavior
Transparency - All decisions must be explainable
Professional - Serious tool for serious users
Critical info always visible:
- Current balance
- Profit/Loss (session and total)
- Stop conditions (win/loss limits)
- Connection status
Emergency stop always accessible:
- Stop button must be visible at all times
- Keyboard shortcut (Ctrl+C, Escape)
- Cannot be hidden behind modals
- Must work even if UI is frozen
No auto-start:
- Bot never starts betting automatically
- User must explicitly click "Start"
- Page reload/refresh never resumes betting
No auto-guessing:
- Invalid input → error message, not silent fix
- Don't assume what user meant
- Don't convert units automatically
No hidden logic:
- All calculations visible in logs
- Strategy decisions must be explainable
- No "magic" behavior
Priority order:
- Running status (most prominent) - Is bot active? Balance? P/L?
- Strategy controls (secondary) - Strategy selector, parameters
- Analytics (tertiary) - Charts, history, statistics
Standard color meanings:
- 🟢 Green: Running, profit, success, connected
- 🔴 Red: Stopped, loss, error, disconnected
- 🟡 Yellow: Paused, warning, simulation mode
- ⚪ Gray: Idle, neutral, disabled
Block invalid actions:
- Invalid input must block Start button
- Show clear error message explaining why
- Do not silently fix user input
- Do not proceed with "best guess"
Explicit units everywhere:
- "0.001 BTC" not "0.001"
- "50.5%" not "50.5"
- "5 bets" not "5"
- Label every number with its unit
Live updates:
- Update display every 250ms during betting
- GUI must always remain responsive
- Use threading for background tasks
- Never block the UI thread
Progress indication:
- Show bet number (e.g., "Bet 47/100")
- Show time elapsed
- Show estimated time remaining (if applicable)
One concept per screen:
- Don't mix betting controls with analytics
- Use tabs/pages for different purposes
- Don't overwhelm with too many options
No duplicate controls:
- One way to start/stop
- One place for each setting
- Avoid redundant buttons
No modal spam:
- Use modals sparingly
- Never block user for non-critical info
- Use inline messages when possible
All decisions explainable:
- Log why each bet amount was chosen
- Show formula/calculation
- Link decisions to strategy rules
Logs are first-class citizens:
- Always visible or easily accessible
- Timestamped and detailed
- Exportable
- Never truncated without warning
No gamification:
- No "streaks", "achievements", "levels"
- No celebratory animations
- No sound effects (optional notification sounds OK)
Neutral wording:
- "Profit/Loss" not "Winnings"
- "Stop" not "Quit" or "Give Up"
- "Strategy" not "System" or "Method"
- Technical and factual
Crash-safe:
- Bet history saved immediately to disk
- Session recoverable after crash
- Settings persisted automatically
Network failure:
- Pause betting immediately
- Show clear notification
- Don't retry automatically
- Let user decide when to resume
Conservative defaults for first run:
- Small bet amounts
- Reasonable win/loss limits
- Safe strategy (e.g., Flat Betting)
- Simulation mode enabled
Dark mode default:
- Dark background (#1a1a1a, #2a2a2a)
- Light text (#e0e0e0, #f0f0f0)
- Accent colors for status (green/red/yellow)
- High contrast for readability
Large, clear buttons:
- Minimum 40px height for clickable elements
- Clear labels (no icons-only buttons)
- Sufficient spacing between elements
- Touch-friendly for tablets
Mobile-friendly / responsive layout:
- Works on desktop, tablet, and mobile
- Adapts to different screen sizes
- Important info visible without scrolling
- No horizontal scroll
Deterministic live updates:
- Update cycle is predictable
- No random delays
- Consistent refresh intervals
- Smooth, not jarring
Charts must not block bot:
- Charts run in separate thread
- Never delay bet execution
- Degrade gracefully (skip frame if needed)
- Can be disabled entirely
Tooltips for strategy parameters:
- Explain what each parameter does
- Show examples
- Include recommended ranges
- Don't require external documentation
Launch command:
python3 gui/app.py # Opens http://localhost:8080
# OR: ./run_nicegui.sh
# OR: ./QUICK_DEPLOY.sh (automated setup)
File structure:
gui/app.py
- Main application entrygui/dashboard.py
- Main dashboard with stats and chartsgui/strategies_ui.py
- Strategy configuration and profilesgui/history.py
- Bet history displaygui/analytics_ui.py
- Analytics dashboard (NEW)gui/settings.py
- Settings and API configurationgui/simulator.py
- Simulation mode UIgui/bot_controller.py
- Bot execution and threadinggui/state.py
- Global state managementgui/charts.py
- Matplotlib chart generationgui/database.py
- SQLite persistencegui/analytics.py
- Statistical calculationsgui/strategy_loader.py
- Dynamic strategy loadinggui/strategy_integration.py
- Strategy execution pipelinegui/live_api.py
- DuckDice API wrapper
Initial state:
- 6 tabs available: Dashboard, Strategies, Simulator, History, Analytics, Settings
- Simulation mode enabled by default
- Start button available (simulation doesn't require API key)
- For live mode: API key required and validated
Launch command:
python duckdice_gui_ultimate.py
Note: Legacy interface. Use NiceGUI web interface for new development.
All features must be implemented:
- No placeholder UI ("Coming Soon")
- No TODOs in production code
- All buttons must work
- All features must be tested
If output too long → split into files:
- Separate concerns into modules
- Don't create monolithic files
- Use clear file/module names
- Follow project structure
Use comments for explanation only:
- Explain why, not what
- Complex algorithms need comments
- Public APIs need docstrings
- No obvious comments ("increment counter")
Prioritize safety and control:
- User safety (can't lose more than intended)
- User control (can stop anytime)
- Clarity (understands what's happening)
- Features (only if above are satisfied)
Reactive, modular, maintainable code:
- Use reactive patterns (observers, events)
- Small, focused functions
- Clear separation of concerns
- Easy to test and debug
Single source of truth:
- One state object for app state
- Components react to state changes
- State changes are logged
- State is serializable
Fail gracefully:
- Catch all exceptions
- Log errors with context
- Show user-friendly messages
- Never crash silently
Resilient API usage:
- Retry with exponential backoff
- Timeout on all requests
- Handle rate limiting
- Log all API calls
Safe threading:
- UI updates only on main thread
- Background work in separate threads
- Use thread-safe queues
- Proper thread cleanup
Must be tested:
- Manual testing with real scenarios
- Edge cases handled
- Error paths work
- UI is responsive
Always test in simulation first:
- No real money at risk
- Same code path as live
- Clearly marked as simulation
- Easy to toggle
All strategies implement:
def calculate_next_bet(self, last_bet, won, balance) -> float:
"""Calculate next bet amount."""
Required metadata:
- Name (clear, descriptive)
- Description (what it does)
- Risk level (Low/Medium/High/Extreme)
- Recommended parameters
- Example behavior
User-configurable:
- Validated ranges
- Clear labels and units
- Tooltips explaining each
- Sensible defaults
Always log:
- Every bet (amount, target, result)
- Strategy decisions
- Balance changes
- Errors and warnings
- Start/stop events
Structured logging:
- Timestamp (ISO 8601)
- Log level (INFO, WARNING, ERROR)
- Context (what was happening)
- Data (relevant values)
Persistent logs:
- Saved to disk immediately
- JSONL format (one JSON object per line)
- Rotation (don't fill disk)
- Exportable
UI must be snappy:
- Button click → feedback < 100ms
- Page load < 1 second
- Chart update < 250ms
- Bet execution < 500ms (excluding API)
Efficient resource use:
- No memory leaks
- CPU usage reasonable
- Network usage minimal
- Disk I/O batched
Full keyboard support:
- Tab through all controls
- Shortcuts for common actions
- Focus indicators visible
- Logical tab order
Accessible to screen readers:
- Semantic HTML (web interface)
- Alt text for images
- ARIA labels where needed
- Proper heading hierarchy
Priority 1 - Production Ready (100%):
- ✅ Live API integration with DuckDice
- ✅ Dynamic strategy loading (17 strategies)
- ✅ Real bet execution (simulation + live modes)
Priority 2 - Enhanced Features (100%):
- ✅ Matplotlib charts (4 types: balance, P/L, distribution, streaks)
- ✅ UI enhancements (spinner, rich notifications, auto-stop alerts)
- ✅ Database persistence (SQLite: bet_history, strategy_profiles, sessions)
Priority 3 - Advanced Features (33%):
- ✅ Analytics dashboard (20+ metrics, historical comparison)
- ⚠️ WebSocket support (optional, not implemented)
- ⚠️ Multi-user authentication (optional, not implemented)
Core Application:
gui/app.py
(100 lines) - Main entry, tab navigationgui/state.py
(150 lines) - Global state with BetRecord dataclassgui/bot_controller.py
(450 lines) - Bot execution, threading, database integration
UI Components:
gui/dashboard.py
(450 lines) - Stats grid, charts, controlsgui/strategies_ui.py
(400 lines) - Strategy config, profile managementgui/analytics_ui.py
(200 lines) - Analytics dashboard with metricsgui/history.py
(250 lines) - Bet history tablegui/settings.py
(300 lines) - API config, stop conditions
Backend Logic:
gui/database.py
(400 lines) - SQLite operations (3 tables)gui/charts.py
(300 lines) - Matplotlib chart generationgui/analytics.py
(350 lines) - Statistical calculationsgui/strategy_loader.py
(200 lines) - Dynamic strategy discoverygui/live_api.py
(150 lines) - DuckDice API client
Testing:
tests/gui/test_gui_components.py
- 7 unit tests (all passing)
bet_history table:
- session_id, timestamp, amount, target, roll, won, profit, balance, strategy
- Indexed on session_id and timestamp
strategy_profiles table:
- name, strategy_name, parameters (JSON), description
sessions table:
- session_id (UUID), strategy_name, balances, stats, timestamps, stop_reason
Low Risk: Flat Betting, Percentage Betting
Medium Risk: D'Alembert, Oscar's Grind, Fibonacci, Reverse D'Alembert
High Risk: Martingale, Anti-Martingale, Labouchere, Paroli, Pyramid, Reverse Pyramid
Complex: Double Street, 1-3-2-6 System, Whittaker, Kelly Criterion, Pluscoup
User Guides:
USER_GUIDE.md
(14.7 KB) - End user manualQUICKSTART.md
- Quick start guideREADME.md
- Project overview
Deployment:
DEPLOYMENT_GUIDE.md
(14.7 KB) - Full deployment instructionsVALIDATION_REPORT.md
(9.5 KB) - Testing and validationDEPLOYMENT_COMPLETE.md
- Deployment summaryQUICK_DEPLOY.sh
- Automated deployment script
Technical:
IMPLEMENTATION_COMPLETE.md
(12.5 KB) - Architecture and featuresTODO_FEATURES.md
- Feature completion statusCONTRIBUTING.md
- Contribution guidelines
- Python 2 compatibility: Some tests fail with Python 2.7 (use Python 3.8+)
- Profile list refresh: Requires manual page refresh after save/delete
- WebSocket: Not implemented (Priority 3 optional)
- Multi-user: Not implemented (Priority 3 optional)
- Making Changes: Edit files in
gui/
directory
- Testing: Run
cd tests/gui && python3 test_gui_components.py
- Running:
python3 gui/app.py
or ./run_nicegui.sh
- Database: Auto-created at
data/duckdice_bot.db
- Charts: Auto-refresh every 10 bets (performance optimization)
# Start application
python3 gui/app.py
# Quick deploy (automated)
./QUICK_DEPLOY.sh
# Run tests
cd tests/gui && python3 test_gui_components.py
# Check database
sqlite3 data/duckdice_bot.db "SELECT * FROM sessions LIMIT 5;"
# Kill port 8080
lsof -ti:8080 | xargs kill -9
Remember: Safety, clarity, and predictability take priority over beauty or cleverness.
If in doubt:
- ✅ Is it safe?
- ✅ Is it clear?
- ✅ Is it predictable?
- ✅ Does it help the user stay in control?
If all four are "yes", proceed. Otherwise, reconsider.
Project Status: ✅ Production Ready
Version: 4.0.0 (NiceGUI Complete Edition)
Last Updated: January 11, 2026
Completion: ~85% (100% of core features)