first (part 2: other directories)

2026-04-16 15:11:25 +03:00
parent 7814e0bc6b
commit 2f0b85a0c7
203 changed files with 59989 additions and 0 deletions
@@ -0,0 +1,80 @@
+# 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.