# 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.