Skip to main content

Ludicé Documentation

Complete documentation for the Ludicé Telegram bot dice-rolling game.

📚 Documentation Index​

Getting Started​

  • Setup Guide - Complete installation and configuration guide
    • Prerequisites and system requirements
    • Environment setup
    • Running the application
    • Troubleshooting

Technical Documentation​

  • Technical Architecture - System design and architecture

    • Architecture overview
    • Component descriptions
    • Data flow diagrams
    • Technology stack
    • Scalability considerations

  • API Documentation - Complete API reference

    • Backend Game API
    • Balance Service API
    • Frontend Bot Integration
    • Authentication (HMAC-SHA256)
    • Error handling

Development​

  • Development Guide - For contributors and developers
    • Development environment setup
    • Code structure
    • Adding features
    • Testing
    • Git workflow

🚀 I want to...​

Get started quickly: → Setup Guide

Understand the architecture: → Technical Architecture

Integrate with the API: → API Documentation

Add new features: → Development Guide

Review legal requirements: → Legal Documents

Project Overview​

What is Ludicé?​

Ludicé is a Telegram bot that lets users play dice-rolling games against each other. Players bet Telegram Stars (in-app currency) and compete to win their opponent's bet.

Key Features​

  • 🎲 Dice Game - Roll dice, highest wins
  • ⭐ Telegram Stars Payment - Buy-in with Telegram's native currency
  • 🔒 Secure - HMAC-SHA256 authenticated API calls
  • ⚖️ Fair - No house edge (100% winner takes all)
  • 🔞 Responsible Gaming - Built-in gambling safeguards

Technology Stack​

LayerTechnology
FrontendPython 3.9+ / aiogram 3.22.0
Backend APIPython 3.9+ / FastAPI 0.119.0
Balance ServiceGo 1.19+ / Gin / Redis
Data StorageJSON files (development)
PaymentTelegram Stars (XTR)
AuthenticationHMAC-SHA256

Architecture Overview​

┌─────────────┐
│ Telegram    │
│ User        │
└──────┬──────┘
       │
       ▼
┌─────────────────────┐
│ Frontend (aiogram)  │
│ - Bot handlers      │
│ - FSM states        │
│ - Payment UI        │
└──────┬──────────────┘
       │ HMAC Auth
       ▼
┌─────────────────────┐
│ Backend (FastAPI)   │
│ - Game logic        │
│ - User management   │
│ - Signature verify  │
└──────┬──────────────┘
       │ HTTP
       ▼
┌─────────────────────┐
│ Balance (Go/Redis)  │
│ - User balances     │
│ - Redis storage     │
└─────────────────────┘

For detailed architecture: → Technical Architecture

Quick Start​

1. Prerequisites​

  • Python 3.9+
  • Go 1.19+
  • Redis
  • Telegram Bot Token

2. Install​

# Clone repository
git clone https://github.com/Wizer27/Ludice.git
cd Ludice

# Setup virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
cd frontend && pip install -r requirements.txt

3. Configure​

Create frontend/.env:

TOKEN=your_telegram_bot_token
SECRET_KEY=your_shared_secret_key
secret_token=your_payment_token

Create backend/secrets.json:

{
    "secret_key": "your_shared_secret_key"
}

4. Run​

# Terminal 1: Backend API
cd backend
python new.py

# Terminal 2: Balance Service
cd backend/redis
go run main.go

# Terminal 3: Bot
cd frontend
python app.py

For detailed setup: → Setup Guide

Game Flow​

User Journey​

  1. Start - User sends /start to bot
  2. Terms - User accepts Terms of Service
  3. Registration - Bot registers user to backend
  4. Main Menu - User sees menu (Roll, Top up, Profile, Help)
  5. Play - User clicks "Roll 🎲" → "Dice 🎲"
  6. Bet - User enters bet amount (min 10 stars)
  7. Match - System finds opponent or creates lobby
  8. Roll - Both players roll dice
  9. Result - Winner gets 100% of both bets

Payment Flow​

  1. Top Up - User clicks "Top up 🔝"
  2. Select Amount - Choose from 15-1,000,000 stars
  3. Pay - Telegram processes payment (Telegram Stars)
  4. Credit - Balance updated (~25% fee applied)

For API details: → API Documentation

Development​

Project Structure​

Ludice/
├── frontend/           # Telegram bot (Python/aiogram)
│   ├── app.py
│   ├── routers/
│   ├── keyboard/
│   └── common/
├── backend/            # Game API (Python/FastAPI)
│   ├── new.py
│   ├── financne.py
│   └── redis/          # Balance service (Go)
├── data/               # JSON data files
├── docs/               # Documentation (you are here!)
│   ├── legal/
│   └── my-docs/        # Docusaurus site
└── requirements.txt

Adding a Feature​

  1. Read Development Guide
  2. Create feature branch: git checkout -b feature/my-feature
  3. Implement changes
  4. Test locally
  5. Submit pull request to dev branch

For contribution guidelines: → Development Guide

API Reference​

Backend Game API (Port 8080)​

Authentication: HMAC-SHA256 signature required

EndpointMethodDescription
/registerPOSTRegister new user
/start/gamePOSTStart/join game
/write/resPOSTSubmit dice result
/leavePOSTLeave lobby

Balance Service API (Port 8000)​

Authentication: None (internal service)

EndpointMethodDescription
/create_userPOSTCreate user account
/get_balanceGETQuery user balance
/modify_balancePOSTAdd/subtract balance

For complete API reference: → API Documentation

Security​

HMAC Authentication​

All frontend → backend requests use HMAC-SHA256 signatures:

# Create signature
data_str = json.dumps(data, sort_keys=True, separators=(',', ':'))
signature = hmac.new(
    SECRET_KEY.encode(),
    data_str.encode(),
    hashlib.sha256
).hexdigest()

# Send with X-Signature header
headers = {"X-Signature": signature}

Rate Limiting​

  • IP-based: 10 requests/minute
  • User-based: 1 request/second minimum

Environment Variables​

Never commit:

  • .env files
  • secrets.json
  • API tokens

For security details: → Technical Architecture

Testing​

Run Tests​

# Python tests
pytest tests/

# Type checking
mypy frontend/ backend/

# Linting
flake8 frontend/ backend/
black --check frontend/ backend/

Manual Testing​

# Test bot
cd frontend
python scripts/test_bot.py

# Test API
python scripts/test_api.py register testuser 123456

# Test balance service
curl http://localhost:8000/get_balance?username=testuser

For testing guide: → Development Guide

Required Actions​

Before deploying to production:

  • Update jurisdiction in Terms of Service
  • Add physical address in Privacy Policy
  • Specify server locations
  • Review with legal counsel
  • Implement terms acceptance tracking
  • Set up age verification
  • Terms of Service (22 sections)
  • Privacy Policy (GDPR/CCPA compliant)
  • Responsible Gambling Policy
  • Bot Summary (quick reference)

For legal implementation: → Legal Documents

Deployment​

Development​

# Run locally (see Quick Start above)

Production (Docker Compose)​

version: '3.8'
services:
  redis:
    image: redis:7-alpine
  backend-api:
    build: ./backend
  balance-service:
    build: ./backend/redis
  bot:
    build: ./frontend
docker-compose up -d

Production (Manual)​

  1. Use process manager (PM2, systemd)
  2. Set up reverse proxy (nginx)
  3. Enable HTTPS (Let's Encrypt)
  4. Configure firewall
  5. Set up monitoring
  6. Implement backups

For deployment guide: → Setup Guide

Troubleshooting​

Common Issues​

Bot won't start → Check TOKEN in .env

Signature verification failed → Ensure SECRET_KEY matches in frontend/.env and backend/secrets.json

Redis connection refused → Start Redis: redis-server

Port already in use → lsof -i :8080 then kill -9 <PID>

For more troubleshooting: → Setup Guide

Resources​

Official Documentation​

Community​

Contributing​

We welcome contributions! Please:

  1. Read Development Guide
  2. Fork the repository
  3. Create feature branch
  4. Make changes
  5. Submit pull request to dev branch

Code Style​

  • Python: Follow PEP 8, use Black formatter
  • Go: Use gofmt
  • Commits: Use Conventional Commits format

License​

Copyright © 2025 Ludicé

See LICENSE file for details.

Support​

For Users​

For Developers​

  • GitHub Issues: Report bugs
  • Documentation: Read this documentation
  • Pull Requests: Contribute code

Changelog​

Version 1.0.0 (January 2025)​

  • Initial release
  • Dice game implementation
  • Telegram Stars payment integration
  • Terms acceptance flow
  • HMAC authentication
  • Rate limiting
  • Comprehensive documentation

Last Updated: January 2025 Documentation Version: 1.0.0