81 lines
4.0 KiB
Markdown
Executable File
81 lines
4.0 KiB
Markdown
Executable File
# 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
|
|
```bash
|
|
# 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.
|