Suggest-Bet Backend Project Documentation

1. Project Overview

Name: Suggest-Bet Backend Purpose: A high-performance, AI-driven sports betting prediction platform. The backend fetches massive amounts of historical and live sports data (Football & Basketball), processes it, stores it in a structured relational database, and feeds it into a specialized Python AI engine ("V8 Model") to generate betting predictions.

2. Technology Stack

Framework: NestJS (Node.js) - Modular, scalable server architecture.
Database: PostgreSQL (Relation DB).
ORM: Prisma - Type-safe database access and schema management.
Language: TypeScript.
AI Engine: Python (custom V8 model), integrated via HTTP/Shell execution.
External Data Source: Mackolik (Scraped via custom Feeder system).

3. Core Architecture

The project follows a modular structure in src/modules:

A. Feeder Module (`src/modules/feeder`)

The most complex and critical part of the system. It handles data ingestion.

FeederService: Orchestrator. Manages historical scans (runHistoricalScan), concurrency, and error handling.
- Optimization: Uses a CONCURRENCY_LIMIT of 5 and a "Smart Retry Queue" to catch 502 errors and race conditions, retrying them sequentially to ensure 100% data integrity.
FeederScraperService: Scrapes raw HTML/JSON from Mackolik.
- Supports Football (events, stats, lineups) and Basketball (quarters, player stats, odds).
- Smart ID extraction (e.g., from URL hashes).
FeederTransformerService: Converts raw scraped data into Prisma-compatible objects.
FeederPersistenceService: Transactional saving of complex relational data (Matches -> Teams, Players, Stats, Odds).

B. AI Integration (`ai-engine`)

A Python-based machine learning engine located in ai-engine/.
AiService (src/modules/ai): Bridges NestJS and Python. Sends match data to the Python script and receives prediction probabilities (Home/Draw/Away, Over/Under, etc.).

C. Other Modules

Matches: API for retrieving match lists, details, and search.
Predictions: Stores and serves AI predictions.
Coupons: Generates daily betting coupons based on high-confidence predictions.
Analysis: analytics and user tracking.

4. Database Schema (Key Models)

Defined in prisma/schema.prisma.

Match: Central entity. Links to HomeTeam, AwayTeam, League.
Team: Stores team info. Now supports logos (via URL) and dual sports (Football/Basketball).
Player: Global player registry.
MatchTeamStats: Detailed stats (Possession, Shots, or Q1/Q2/Q3/Q4 for basketball).
MatchPlayerStats: Granular player performance (Minutes, Goals, Rebounds, Assists).
Odd / OddSelection: Stores betting market odds (1-X-2, Alt/Ust, etc.).

5. Critical Workflows & Scripts

Historical Data Feeder

Command: npm run feeder:historical Function: Scrapes past data starting from 2024-01-01.

Dual Mode: Processes both Football and Basketball automatically.
Robustness: Includes a sophisticated retry mechanism. If a Mackolik endpoint returns 502 or a DB constraint fails, it queues the match and retries it sequentially at the end of the batch.

Basketball-Only Feeder

Command: npm run feeder:basketball Function: Targeted scrape for basketball matches only. Useful for filling gaps or testing.

6. Setup & Development

# Install dependencies
npm install

# Setup Database
npx prisma generate
npx prisma db push

# Run Development Server
npm run start:dev

# Run Feeder (Data Collection)
npm run feeder:historical

7. Recent Customizations (Context for AI)

Speed Optimization: The feeder runs 5 concurrent requests.
Basketball Logic: Custom parsers for Quarter scores and "Box Score" based player stats were added.
Player IDs: We extract stable Hash IDs from Mackolik URLs (e.g., 92jre0fco...) instead of generating them from names.

This document serves as the absolute source of truth for understanding the codebase capabilities and architecture.

4.0 KiB Executable File Raw Blame History