System architecture

Overview

PROPPR is a microservices-based betting intelligence platform that monitors real-time betting markets, calculates expected value, detects arbitrage opportunities, and delivers personalized alerts via Telegram.

The platform processes odds from 100+ bookmakers across 50+ sports, generating thousands of alerts daily for value bets, arbitrage, and player props.

Architecture Diagram

Data Flow

The PROPPR data pipeline follows this sequence:

External Data Collection

Three parallel data streams continuously fetch market data:

UnifiedAPIPoller polls REST API every 60 seconds
WebsocketUpdater receives real-time odds via WebSocket
StatsUpdateFM fetches player/team stats from FotMob

From UnifiedAPIPoller/runners/run_unified_poller.py:28:

def main():
    """Start the Unified API Poller"""
    logger.info("PROPPR Unified API Poller Starting")
    from PROPPR.UnifiedAPIPoller.core.unified_poller import main as poller_main
    poller_main()

Data Normalization

Raw data is normalized through SharedServices modules:

LeagueNormalizer: Standardizes league names across sources
MarketMapper: Maps markets to canonical format
FixtureMatching: Matches games across different APIs

From SharedServices/mapping/league_normalizer.py:4:

class LeagueNormalizer:
    """
    Centralized service for normalizing league names to prevent duplicates
    caused by data source inconsistencies.
    """
    LEAGUE_NORMALIZATION_MAP = {
        "LaLiga": "La Liga",
        "Liga Portugal": "Primeira Liga",
        "UEFA Conference League": "Europa Conference League",
        # ... 50+ mappings
    }

MongoDB Storage

Normalized data is stored in MongoDB collections:

Collection	Purpose	Updated By
`all_positive_alerts`	Player prop opportunities	UnifiedAPIPoller
`all_positive_team_alerts`	Team market opportunities	UnifiedAPIPoller
`cerebro_positive_alerts`	EV bets (Pinnacle-based)	EVBot scanner
`arbitrage_bets`	Cross-bookmaker arbs	ArbBot scanner
`horse_racing_arbs`	Horse racing value bets	HorseBot scanner
`user_tracked_bets`	User bet tracking	BetTrackingSystem

From config/settings.py:20:

COLLECTIONS = {
    'player_alerts': 'all_positive_alerts',
    'team_alerts': 'all_positive_team_alerts',
    'cerebro_alerts': 'cerebro_positive_alerts',
    'arbitrage_bets': 'arbitrage_bets',
    'user_tracked_bets': 'user_tracked_bets',
}

Alert Processing

Alert bots query MongoDB and apply user filters:

Minimum/maximum odds thresholds
League preferences (Main leagues vs. all)
Market selections (goals, assists, corners, etc.)
Time-to-kickoff requirements
Bookmaker preferences

Each bot maintains a sent alerts cache to prevent duplicates.

Telegram Delivery

Formatted alerts are sent via Telegram Bot API:

Rich formatting with market emojis
Bookmaker deep links for one-click betting
Kelly criterion stake recommendations
Real-time odds updates on button clicks

From PropprTeamBot/core/bot/team_bot.py:42:

from telegram.ext import (
    Updater, CommandHandler, CallbackQueryHandler,
    MessageHandler, Filters, CallbackContext
)

# Import shared services
from PROPPR.SharedServices.tracking import BetTrackingSystem
from PROPPR.SharedServices.mapping import MarketResultMapper
from PROPPR.SharedServices.grading.processors import ImmediateBetGrader

Result Grading

Grading services update bet outcomes:

Poll FotMob API for match results
Calculate win/loss for tracked bets
Update Google Sheets with P&L
Send result notifications to users

From SharedServices/grading/processors/immediate_bet_grader.py:23:

class ImmediateBetGrader:
    """Service for grading bets immediately when fixture is finished"""
    
    def __init__(self, api_token: str = '', bot_type: str = 'player'):
        self.bot_type = bot_type
        self.fotmob = get_fotmob_service()

Alert Bots

PROPPR includes 6 specialized alert bots, each monitoring different market types:

PropprTeamBot

Team Market AlertsMonitors team-level betting markets:

Goals (Over/Under, Both Teams to Score)
Corners (Total, Asian Handicap)
Cards (Yellow, Red, Bookings)
Shots (Total, On Target)
Fouls, Offsides, Possession

Runner: PropprTeamBot/runners/run_team_bot.py

PropprPlayerBot

Player Prop AlertsMonitors individual player markets:

Goals, Assists, Goal Contributions
Shots, Shots on Target
Passes, Key Passes, Long Balls
Tackles, Interceptions, Duels
Dribbles, Crosses, Touches

Runner: PropprPlayerBot/runners/run_player_bot.py

PropprEVBot

Expected Value AlertsCalculates EV using Pinnacle as sharp reference:

Compares soft bookmaker odds to Pinnacle
Filters by minimum EV% (configurable)
Kelly criterion stake sizing
Line movement tracking

From PropprEVBot/core/bot/ev_bot.py:40:

# Import request tracker for API rate limiting
from PROPPR.SharedServices.tracking import get_tracker, KEY_MAIN
main_request_tracker = get_tracker(KEY_MAIN)

Runner: PropprEVBot/core/bot/ev_bot.py

PropprArbBot

Arbitrage DetectionScans for guaranteed profit opportunities:

Cross-bookmaker arbitrage
Automatic stake calculation
Exchange commission handling
Sharp bookmaker filtering

From PropprArbBot/core/bot/arb_bot.py:30:

from PROPPR.PropprArbBot.services.database.database import DatabaseManager
from PROPPR.PropprArbBot.services.api.api_service import ArbitrageAPIService
from PROPPR.PropprArbBot.core.scanner.db_odds_arbitrage_scanner import DBOddsArbitrageScanner

Runner: PropprArbBot/core/bot/arb_bot.py

PropprHorseBot

Horse Racing AlertsUK horse racing value bets:

Win/Place markets
Value detection vs. market consensus
Daily summaries with results
Time-windowed alerts (configurable)

From PropprHorseBot/core/bot/horse_bot.py:23:

from PROPPR.PropprHorseBot.services.database.connection import HorseBotDatabase
from PROPPR.PropprHorseBot.core.horse_alert_formatter import HorseAlertFormatter
from PROPPR.PropprHorseBot.core.filters.filters import HorseRacingFilter

Runner: PropprHorseBot/core/bot/horse_bot.py

OvertimeBot

Blockchain BettingAutomated betting on Optimism chain:

Overtime Markets protocol integration
Wallet management (encrypted keys)
Automatic bet placement
Gas optimization

From OvertimeBot/core/bot/overtime_bot.py:69:

from PROPPR.OvertimeBot.services.alerts import OvertimeAlertProcessor, OvertimeBetPlacer
from PROPPR.OvertimeBot.services.blockchain import OvertimeContractService, OvertimeWalletService

Runner: OvertimeBot/core/bot/overtime_bot.py

Data Services

Three core services populate MongoDB with real-time market data:

WebsocketUpdater

Real-time odds via WebSocket connections Maintains persistent WebSocket connections to odds providers for instant updates:

Connection Management: Auto-reconnect on disconnect
Rate Limiting: Respects provider limits
Data Validation: Filters invalid/stale data
MongoDB Updates: Upserts odds with timestamps

From WebsocketUpdater/runners/run_websocket_updater.py:28:

def main():
    """Start the WebSocket updater"""
    logger.info("PROPPR WebSocket Updater Starting")
    from PROPPR.WebsocketUpdater.core.websocket_updater import main as ws_main
    ws_main()

Configuration: WebsocketUpdater/config/

UnifiedAPIPoller

REST API polling at regular intervals Polls multiple odds APIs on a schedule (default: 60 seconds):

Multi-source: Supports OddsAPI, custom feeds
Rate Limiting: Managed via RequestTracker
Transformation: Normalizes to unified format
Matching: Deduplicates across sources

From UnifiedAPIPoller/runners/run_unified_poller.py:28:

def main():
    """Start the Unified API Poller"""
    logger.info("PROPPR Unified API Poller Starting")
    from PROPPR.UnifiedAPIPoller.core.unified_poller import main as poller_main
    poller_main()

Key Configuration (from config/settings.py:36):

POLLING_INTERVAL = 60  # seconds
DEFAULT_GRADING_INTERVAL = 60  # seconds

StatsUpdateFM

Player/team statistics pipeline Fetches detailed stats from FotMob for predictive models:

Fixtures: Upcoming matches with lineups
Player Stats: Goals, assists, xG, shot accuracy
Team Stats: Possession, corners, cards
Projections: Predicted player output

From StatsUpdateFM/runners/run_stats_pipeline.py:28:

def main():
    """Start the Stats Pipeline"""
    logger.info("StatsUpdateFM Pipeline Starting")
    from PROPPR.StatsUpdateFM.core.pipeline.stats_update import main as pipeline_main
    pipeline_main()

FotMob Service (from SharedServices/api/fotmob_service.py:30):

class FotMobAPIService:
    """Service for interacting with FotMob API"""
    
    BASE_URL = "https://www.fotmob.com/api"
    DEFAULT_HEADERS = {
        'User-Agent': 'Mozilla/5.0 ...',
        'Accept': 'application/json',
    }

SharedServices Modules

Shared utilities used across all bots:

Grading System

Unified bet result gradingLocation: SharedServices/grading/

ImmediateBetGrader: Grades finished fixtures on-demand
Scheduler: Periodic grading jobs for pending bets
Processors: Market-specific result calculation

From SharedServices/grading/processors/immediate_bet_grader.py:23:

class ImmediateBetGrader:
    """Service for grading bets immediately when fixture is finished"""
    
    def __init__(self, api_token: str = '', bot_type: str = 'player'):
        self.bot_type = bot_type
        self.fotmob = get_fotmob_service()
    
    def is_fixture_finished(self, fixture_data: Dict) -> bool:
        """Check if fixture has finished (FotMob format)"""
        is_finished = self.fotmob.is_fixture_finished(fixture_data)
        return is_finished

Grading Flow:

Query MongoDB for ungraded bets
Fetch fixture results from FotMob
Apply market-specific grading logic
Update bet status (Won/Lost/Push)
Calculate profit/loss
Sync to Google Sheets

Mapping Services

Data normalization and entity matchingLocation: SharedServices/mapping/LeagueNormalizer (league_normalizer.py:4):

class LeagueNormalizer:
    """
    Centralized service for normalizing league names
    """
    LEAGUE_NORMALIZATION_MAP = {
        "LaLiga": "La Liga",
        "Liga Portugal": "Primeira Liga",
        # ... 50+ variations
    }

MarketMapper (market_mapper.py):

Maps bookmaker market names to canonical format
Handles regional variations (US vs. EU odds)
Normalizes player/team names

FixtureMatchingUtils (fixture_matching_utils.py):

Fuzzy matching for team names
Kickoff time comparison
Cross-source fixture linking

CanonicalMarkets (canonical_markets.py):

Defines standard market types
Validation rules for each market
Conversion factors (Asian lines, etc.)

Tracking System

User bet tracking and reconstructionLocation: SharedServices/tracking/BetTrackingSystem (bet_tracking_system.py):

from PROPPR.SharedServices.tracking import BetTrackingSystem

# Track a user's bet
tracker = BetTrackingSystem(mongo_client, db_name)
tracker.track_bet(
    user_id=123456,
    fixture_id="12345",
    market="Goals",
    selection="Over 2.5",
    odds=2.10,
    stake=10.00
)

AlertReconstructionService (alert_reconstruction_service.py):

Rebuilds alert data from message IDs
Links tracked bets to original alerts
Handles edited/deleted messages

RequestTracker (request_tracker.py):

API rate limit management
Per-key quota tracking
Automatic key rotation

From SharedServices/tracking/request_tracker.py:

from PROPPR.SharedServices.tracking import get_tracker, KEY_MAIN

tracker = get_tracker(KEY_MAIN)
if tracker.can_make_request():
    # Make API call
    tracker.record_request()

Configuration & Presets

Centralized bot configurationLocation: SharedServices/config/

shared_config.py: MongoDB, API keys, defaults
presets.py: Optimal market presets per bot

From config/credentials.py:143:

def get_mongo_connection_string() -> str:
    """
    Get MongoDB connection string based on environment.
    Production (Linux): Uses local MongoDB on Hetzner
    Development (Mac): Uses Atlas or SSH tunnel
    """
    if is_production():
        return _get_env('MONGODB_URI_PRODUCTION', default="mongodb://127.0.0.1:27017/...")
    else:
        return _get_env('MONGODB_URI_DEVELOPMENT', default="mongodb://127.0.0.1:27017/...")

API Clients

Reusable API service wrappersLocation: SharedServices/api/FotMobService (fotmob_service.py:30):

class FotMobAPIService:
    """Service for interacting with FotMob API"""
    BASE_URL = "https://www.fotmob.com/api"
    
    def get_fixture_details(self, fixture_id: int) -> Dict:
        """Get detailed fixture data including lineups and stats"""
    
    def get_player_stats(self, player_id: int) -> Dict:
        """Get player career and season statistics"""
    
    def is_fixture_finished(self, fixture_data: Dict) -> bool:
        """Check if a fixture has finished"""

OddsAPIClient (used by UnifiedAPIPoller):

REST endpoint calls
Response parsing
Error handling

i18n (Internationalization)

Multi-language supportLocation: SharedServices/i18n/From SharedServices/__init__.py:20:

from PROPPR.SharedServices.i18n import t, SUPPORTED_LANGUAGES

# Usage in bots
welcome_message = t('welcome_message', lang=user_lang)

Supported Languages: English, Spanish, Portuguese, French, German

Utilities

Text normalization and helpersLocation: SharedServices/utils/

text_normalization.py: Unicode handling, accent removal
bookmaker_link_generator.py: Deep link creation

From SharedServices/__init__.py:19:

from PROPPR.SharedServices.utils import comprehensive_normalize_text

# Normalize player names for matching
normalized = comprehensive_normalize_text("Cristiano Ronaldo")

Deployment Architecture

PROPPR runs on a Hetzner dedicated server with systemd service management:

Production Environment

Server: Ubuntu 22.04 LTS on Hetzner (46.224.85.158) Directory Structure:

/opt/proppr/
├── config/                    # Credentials and settings
│   ├── credentials.py
│   └── settings.py
├── SharedServices/            # Shared modules
├── PropprTeamBot/             # Team bot service
├── PropprPlayerBot/           # Player bot service
├── PropprEVBot/               # EV bot service
├── PropprArbBot/              # Arb bot service
├── PropprHorseBot/            # Horse bot service
├── OvertimeBot/               # Overtime bot service
├── WebsocketUpdater/          # WebSocket data service
├── UnifiedAPIPoller/          # API polling service
├── StatsUpdateFM/             # Stats pipeline
├── .env                       # Environment variables (sensitive)
├── credentials.json           # Google Sheets service account (sensitive)
└── turnstile_cookies.json     # FotMob cookies (sensitive)

Systemd Services

Each bot runs as a systemd unit:

team-bot.service

[Unit]
Description=PROPPR Team Bot
After=network.target mongodb.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/proppr
ExecStart=/usr/bin/python3 -m PROPPR.PropprTeamBot.runners.run_team_bot
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Service Management:

# Start/stop services
systemctl start team-bot
systemctl stop team-bot
systemctl restart team-bot

# View status
systemctl status team-bot

# View logs
journalctl -u team-bot -f

# List all PROPPR services
systemctl list-units 'proppr-*'

Deployment Process

From scripts/deploy/push_and_restart.sh:1:

#!/bin/bash
# PROPPR Deployment Script
SERVER="46.224.85.158"
PROPPR_LOCAL="/Users/zinq/PycharmProjects/Cerebro/PROPPR"
PROPPR_REMOTE="/opt/proppr"

# Sync files to server
rsync -avz --exclude '__pycache__' --exclude '*.pyc' \
    "$PROPPR_LOCAL/" root@$SERVER:"$PROPPR_REMOTE/"

# Restart services
ssh root@$SERVER "systemctl restart proppr-*"

Deploy Workflow:

Push Code

Sync updated code to production server:

./scripts/deploy/push_and_restart.sh

Service Selection

Choose which services to restart:

Individual bot (Team, Player, EV, etc.)
Data services (WebSocket, Poller, Stats)
All services

Automatic Restart

Script automatically restarts selected systemd units:

ssh root@server "systemctl restart team-bot"

Verify Deployment

Check logs to ensure services started:

ssh root@server "journalctl -u team-bot -n 50"

MongoDB Schema

Key collections and document structures:

Player Alerts (`all_positive_alerts`)

{
  "_id": ObjectId("..."),
  "fixture_id": "12345",
  "league": "Premier League",
  "home_team": "Arsenal",
  "away_team": "Chelsea",
  "kickoff_time": ISODate("2026-03-05T15:00:00Z"),
  "player_name": "Bukayo Saka",
  "market": "Shots On Target",
  "line": 2.5,
  "selection": "Over",
  "odds": 2.10,
  "bookmaker": "Bet365",
  "expected_value": 8.5,
  "timestamp": ISODate("2026-03-04T10:30:00Z")
}

Team Alerts (`all_positive_team_alerts`)

{
  "_id": ObjectId("..."),
  "fixture_id": "12345",
  "league": "La Liga",
  "home_team": "Barcelona",
  "away_team": "Real Madrid",
  "kickoff_time": ISODate("2026-03-05T20:00:00Z"),
  "market": "Total Corners",
  "line": 10.5,
  "selection": "Over",
  "odds": 1.95,
  "bookmaker": "Betfair",
  "timestamp": ISODate("2026-03-04T11:00:00Z")
}

Arbitrage Bets (`arbitrage_bets`)

{
  "_id": ObjectId("..."),
  "fixture_id": "12345",
  "league": "Bundesliga",
  "home_team": "Bayern Munich",
  "away_team": "Borussia Dortmund",
  "kickoff_time": ISODate("2026-03-05T17:30:00Z"),
  "market": "Match Result",
  "legs": [
    {
      "selection": "Bayern Munich",
      "odds": 1.75,
      "bookmaker": "Bet365",
      "stake": 57.14
    },
    {
      "selection": "Draw or Dortmund",
      "odds": 2.40,
      "bookmaker": "Pinnacle",
      "stake": 42.86
    }
  ],
  "margin": 2.5,  // 2.5% guaranteed profit
  "total_stake": 100.00,
  "guaranteed_profit": 2.50,
  "timestamp": ISODate("2026-03-04T12:00:00Z")
}

Tracked Bets (`user_tracked_bets`)

{
  "_id": ObjectId("..."),
  "user_id": 123456789,
  "fixture_id": "12345",
  "player_name": "Erling Haaland",
  "market": "Anytime Goalscorer",
  "selection": "Yes",
  "odds": 1.80,
  "stake": 10.00,
  "bookmaker": "Bet365",
  "status": "pending",  // pending | won | lost | void
  "result": null,
  "profit_loss": null,
  "tracked_at": ISODate("2026-03-04T13:00:00Z"),
  "graded_at": null
}

Performance Characteristics

Throughput

Odds Updates: 1,000+ per minute (WebSocket)
API Polls: 60-second intervals
Alerts Sent: 500+ per hour peak
Database Queries: 10,000+ per hour

Latency

WebSocket Update → MongoDB: <100ms
Alert Detection → Telegram: <2 seconds
User Command → Response: <500ms
Grading Check: Every 60 seconds

Reliability

Uptime: 99.5% (systemd auto-restart)
Data Freshness: <1 minute
Duplicate Prevention: 99.9%
Rate Limit Compliance: 100%

Scalability

Concurrent Users: 1,000+
Active Subscriptions: 5,000+
MongoDB Storage: 100GB+
Daily Alerts: 10,000+

Next Steps

Quickstart

Get PROPPR running locally in 10 minutes

Development

Contributing guide and code structure

API Reference

Complete API documentation for all modules

Deployment

Production deployment and monitoring

Get started

Services

Alert bots

Data services

Shared services

Configuration

Deployment

Development

​Overview

​Architecture Diagram

​Data Flow

​Alert Bots

PropprTeamBot

PropprPlayerBot

PropprEVBot

PropprArbBot

PropprHorseBot

OvertimeBot

​Data Services

​WebsocketUpdater

​UnifiedAPIPoller

​StatsUpdateFM

​SharedServices Modules

​Deployment Architecture

​Production Environment

​Systemd Services

​Deployment Process

​MongoDB Schema

​Player Alerts (all_positive_alerts)

​Team Alerts (all_positive_team_alerts)

​Arbitrage Bets (arbitrage_bets)

​Tracked Bets (user_tracked_bets)

​Performance Characteristics

Throughput

Latency

Reliability

Scalability

​Next Steps

Quickstart

Development

API Reference

Deployment

Build docs developers (and LLMs) love

Overview

Architecture Diagram

Data Flow

Alert Bots

Data Services

WebsocketUpdater

UnifiedAPIPoller

StatsUpdateFM

SharedServices Modules

Deployment Architecture

Production Environment

Systemd Services

Deployment Process

MongoDB Schema

Player Alerts (`all_positive_alerts`)

Team Alerts (`all_positive_team_alerts`)

Arbitrage Bets (`arbitrage_bets`)

Tracked Bets (`user_tracked_bets`)

Performance Characteristics

Next Steps