iddaai-be/project_summary.md

Suggest-Bet-BE — Comprehensive Project Summary

Son güncelleme: 2026-03-12
Bu doküman, projeyi hiç bilmeyen bir AI veya geliştiricinin projeyi A-Z anlaması için hazırlanmıştır.

---

1. Proje Amacı ve Genel Bakış

Suggest-Bet-BE, yapay zeka destekli bir spor bahis tahmin ve analiz platformu backend servisidir. Platform, kullanıcılara:

• Futbol ve basketbol maçları için AI destekli tahminler sunar
• Akıllı kupon önerileri oluşturur (SAFE, BALANCED, AGGRESSIVE, VALUE, MIRACLE stratejileri)
• Canlı skor takibi ve oran izleme sağlar
• Mackolik.com üzerinden veri scraping ile güncel ve tarihsel maç verileri toplar
• Google Gemini AI ile doğal dil maç yorumu üretir
• Kullanıcı kuponlarını kaydeder ve sonuçlarını takip eder (ROI, Win Rate)

Teknoloji Stack

Katman	Teknoloji
Backend (API)	NestJS 11 (TypeScript)
AI Engine	Python FastAPI (v20+)
Veritabanı	PostgreSQL 16 + Prisma ORM
Kuyruk	BullMQ + Redis (Opsiyonel)
Cache	Redis veya In-Memory fallback
Auth	JWT + Passport (Access + Refresh Token)
AI	Google Gemini API, Custom Python ML Engine
Scraping	Axios + Cheerio (Mackolik HTML parsing)
Loglama	Pino (Structured Logging)
i18n	nestjs-i18n (TR, EN)
API Docs	Swagger (NestJS/Swagger)
Deploy	Docker + Docker Compose
Social	Twitter API v2 (Social poster)

---

2. Mimari Genel Bakış

┌──────────────────────────────────────────────────────────────────┐
│                        CLIENTS (Web/Mobile)                       │
└───────────────────────────────┬──────────────────────────────────┘
                                │ HTTP/REST
┌───────────────────────────────▼──────────────────────────────────┐
│                    NestJS Backend (Port 3005)                      │
│  ┌─────────┬──────────┬──────────┬──────────┬─────────────────┐  │
│  │  Auth   │  Admin   │ Matches  │ Leagues  │  Predictions    │  │
│  │ Module  │ Module   │  Module  │  Module  │   Module        │  │
│  ├─────────┼──────────┼──────────┼──────────┼─────────────────┤  │
│  │ Coupons │ Analysis │  Gemini  │ Social-  │    Health       │  │
│  │ Module  │  Module  │  Module  │ Poster   │   Module        │  │
│  └─────────┴──────────┴──────────┴──────────┴─────────────────┘  │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  Services: AiService | MatchAnalysis | Scraper              │ │
│  ├──────────────────────────────────────────────────────────────┤ │
│  │  Tasks: DataFetcher (Cron) | LiveUpdater | LimitResetter    │ │
│  ├──────────────────────────────────────────────────────────────┤ │
│  │  Feeder: FeederService | Scraper | Transformer | Persistence│ │
│  └──────────────────────────────────────────────────────────────┘ │
└────┬─────────────────┬────────────────────┬──────────────────────┘
     │                 │                    │
     ▼                 ▼                    ▼
┌─────────┐    ┌──────────────┐    ┌──────────────────┐
│PostgreSQL│    │ Redis/BullMQ │    │ AI Engine (py)   │
│  (3.6GB) │    │  (Opsiyonel) │    │ FastAPI:8000     │
└─────────┘    └──────────────┘    └──────────────────┘
                                           │
                                   ┌───────▼───────┐
                                   │ Mackolik API   │
                                   │ (Veri Kaynağı) │
                                   └───────────────┘

---

3. Veritabanı Şeması (27 Tablo)

3.1 Enum'lar

Enum	Değerler
Sport	football, basketball
UserRole	user, superadmin
SubscriptionStatus	free, active, expired
PlayerPosition	goalkeeper, defender, midfielder, striker
EventType	goal, card, substitute
MatchPosition	home, away

3.2 Temel Tablolar ve İlişkileri

Spor Verileri (Büyük Tablolar)

Tablo	Kayıt (~)	Açıklama
matches	237K	Kalıcı maç kayıtları (finished maçlar)
live_matches	82	Aktif/yaklaşan canlı maçlar (günlük döngüsel)
match_player_participation	3.3M	Oyuncu maç katılımları (ilk 11 + yedek)
match_player_events	1.5M	Maç olayları (gol, kart, oyuncu değişikliği)
match_player_stats	345K	Oyuncu istatistikleri (basketbol odaklı)
match_team_stats	311K	Takım istatistikleri (possession, shots, basketbol box score)
match_officials	—	Hakem bilgileri
match_ai_features	—	AI feature vektörleri (ELO, form skoru, eksik oyuncu etkisi)

Oran/Bahis Verileri

Tablo	Kayıt (~)	Açıklama
odd_categories	3.2M	Bahis kategorileri (Maç Sonucu, Alt/Üst vb.)
odd_selections	8.5M	Bahis seçimleri (1, X, 2, Alt, Üst vb.) ve oranları
odds_history	—	Oran değişim geçmişi

Referans Verileri

Tablo	Kayıt (~)	Açıklama
countries	160	Ülkeler
leagues	1,505	Ligler (Süper Lig, Premier League vb.)
teams	19,595	Takımlar
players	217K	Oyuncular
official_roles	—	Hakem rolleri

Kullanıcı ve Sistem

Tablo	Açıklama
users	Kullanıcı hesapları (email, role, subscription)
refresh_tokens	JWT refresh tokenları
usage_limits	Günlük analiz/kupon kullanım limitleri
user_coupons	Kullanıcı kuponları (PENDING/WON/LOST)
user_coupon_items	Kupon içindeki tekil bahisler
analyses	Kullanıcı analiz geçmişi (JSON)
predictions	AI tahmin cache (6 saat TTL)
ai_predictions_log	AI tahmin logları (accuracy tracking)
app_settings	Uygulama ayarları (key-value)
translations	Çeviri verileri (DB-tabanlı i18n)

3.3 Kritik İlişkiler

Country 1──N League 1──N Match N──1 Team (home/away)
Match 1──N OddCategory 1──N OddSelection 1──N OddsHistory
Match 1──N MatchPlayerParticipation N──1 Player
Match 1──N MatchPlayerEvents N──1 Player
Match 1──1 Prediction
Match 1──1 MatchAiFeature
User 1──N Analysis
User 1──N UserCoupon 1──N UserCouponItem N──1 Match
User 1──1 UsageLimit

---

4. NestJS Modülleri (12 Modül)

4.1 Auth Module (src/modules/auth/)

JWT tabanlı kimlik doğrulama sistemi.

Dosya	Açıklama
auth.controller.ts	Register, Login, Refresh, Logout endpointleri
auth.service.ts	bcrypt ile şifre hash, JWT token üretimi, refresh token yönetimi
guards/auth.guards.ts	JwtAuthGuard, RolesGuard, PermissionsGuard (global)
strategies/jwt.strategy.ts	Passport JWT strategy
dto/auth.dto.ts	RegisterDto, LoginDto, RefreshTokenDto, TokenResponseDto

Akış: Register → Password hash (bcrypt, 12 rounds) → User + UsageLimit oluştur → JWT Access (15m) + Refresh Token (7d) üret

4.2 Admin Module (src/modules/admin/)

Superadmin yönetim paneli. @Roles('superadmin') decorator ile korunur.

Fonksiyonlar:

• Kullanıcı yönetimi: Listeleme, detay, rol değiştirme, abonelik güncelleme, aktif/pasif toggle, soft delete
• App Settings: Key-value ayar okuma/yazma (Redis cache ile)
• Usage Limits: Tüm kullanıcı limitlerini listeleme ve toplu sıfırlama
• Analytics: Toplam kullanıcı, aktif, premium, maç ve tahmin sayıları

4.3 Matches Module (src/modules/matches/)

Maç listeleme ve detay servisi.

Metot	Açıklama
findMatches()	Filtreleme (sport, league, status, date, team) ile maç arama. live_matches tablosundan
findUpcomingMatches()	Kupon üretici için yaklaşan maçları bulma (son 24 saat dahil)
getMatchesAndStructureByIds()	Maçları lig bazında grupla, odds JSON'ı yapılandır, frontend formatına dönüştür
getActiveLeagues()	Raw SQL ile aktif ligleri ve canlı maç sayılarını getir (Mackolik-tarzı öncelik sıralama)
listMatches()	Sayfalı maç listesi (matches tablosundan)
getMatchDetailsById()	Tam maç detayı: kadro, istatistik, oran, olaylar. Önce matches, bulamazsa live_matches

Önemli: Takım logoları için https://file.mackolikfeeds.com/teams/{teamId} URL şablonu kullanılır.

4.4 Leagues Module (src/modules/leagues/)

Lig, ülke ve takım keşif servisi.

Fonksiyonlar: Ülke listesi, Lig listesi (sport filtre), Takım arama, Takım detay, Takım son maçları, Head-to-head karşılaştırma

4.5 Predictions Module (src/modules/predictions/)

AI tahmin servisi. Redis/BullMQ gerektirir (conditional module loading).

Dosya	Açıklama
predictions.controller.ts	health, upcoming, value-bets, history, getPrediction, generate, smart-coupon
predictions.service.ts	BullMQ kuyruğu ile tahmin işleme, cache (6 saat TTL, v20plus model check)
queues/predictions.queue.ts	BullMQ kuyruk yöneticisi
queues/predictions.processor.ts	Kuyruk işleyici (worker)
services/ai-feature-store.service.ts	AI feature hesaplama (V17, şu an devre dışı)

Akış: İstek → Cache kontrolü (Prediction tablosu, 6 saat TTL) → BullMQ kuyruğa ekle → AI Engine çağır → Sonuç cache'le

4.6 Coupons Module (src/modules/coupons/)

Akıllı kupon üretici ve kullanıcı kupon yönetimi.

Servis	Açıklama
SmartCouponService	AI Engine v20+ ile maç analizi, kupon üretimi, Gemini ile Türkçe yorum. 5 strateji destekler
UserCouponService	Kupon oluşturma, bahis settlement (MS 1/X/2, Alt/Üst, KG Var/Yok), kullanıcı istatistikleri (ROI, Win Rate)
CouponsService	Legacy servis (şu an boş)

Kupon Stratejileri:

• SAFE — Düşük risk, yüksek güvenilirlik (%78+ confidence, 2 maç)
• BALANCED — Orta risk/oran dengesi
• AGGRESSIVE — Yüksek oran, düşük güvenilirlik
• VALUE — EV+ (Expected Value pozitif) bahisler
• MIRACLE — Çok yüksek oran, çok düşük güvenilirlik

4.7 Analysis Module (src/modules/analysis/)

Maç analiz orkestratörü.

Fonksiyonlar:

• analyzeCoupon() — Çoklu maç analizi. URL parse → Scrape → AI Engine çağrısı
• checkUsageLimit() — Free (10 analiz/3 kupon) vs Premium (50 analiz/10 kupon) limit kontrolü
• recordUsage() — Kullanım kaydı
• getAnalysisHistory() — Analiz geçmişi

4.8 Gemini Module (src/modules/gemini/)

Google Gemini AI entegrasyonu. ENABLE_GEMINI=true ve GOOGLE_API_KEY gerektirir.

API'ler:

• generateText() — Tek prompt ile metin üretimi
• chat() — Multi-turn sohbet
• generateJSON<T>() — Yapısal JSON üretimi (schema destekli)

Kullanım: Maç yorumu üretimi (SmartCouponService içinde, Türkçe, bahis terminolojisi ile)

4.9 Social Poster Module (src/modules/social-poster/)

Sosyal medya paylaşım sistemi (Twitter).

Servis	Açıklama
twitter.service.ts	Twitter API v2 ile tweet gönderimi
image-renderer.service.ts	Canvas ile tahmin kartı görsel üretimi
caption-generator.service.ts	Gemini ile paylaşım metni üretimi
social-poster.service.ts	Orkestratör: tahmin → görsel → metin → paylaş
meta.service.ts	Meta (Instagram/Facebook) entegrasyonu (yapılacak)

4.10 Feeder Module (src/modules/feeder/)

Tarihsel veri toplama sistemi (Mackolik scraping).

Servis	Açıklama
feeder.service.ts	Ana orkestratör. Tarihsel tarama (2023-06-01'den bugüne), ters kronolojik, resume desteği
feeder-scraper.service.ts	HTTP istekleri: livescores, match header, key events, stats, lineups, odds
feeder-transformer.service.ts	Ham veriyi DB modeline dönüştürme
feeder-persistence.service.ts	Prisma ile veritabanına kayıt, duplicate kontrolü, state yönetimi

Konfigürasyon: Concurrency=20, 300ms delay, 50 max retry, 502 exponential backoff

4.11 Health Module (src/modules/health/)

Sistem sağlık kontrolleri: liveness, readiness, AI Engine health.

4.12 Users Module (src/modules/users/)

Kullanıcı CRUD operasyonları. BaseController/BaseService kalıtımı ile generic yapı.

---

5. Servisler (src/services/)

Servis	Dosya	Açıklama
AiService	ai.service.ts	Python AI Engine bridge. POST /v20plus/analyze/{matchId} çağırır, response'u frontend kontratına map'ler. Analysis strategy üretir (oran bazlı taktik)
MatchAnalysisService	match-analysis.service.ts	7 fazlı analiz orkestratörü: URL Parse → Scrape → Python Engine → Strategy → Similar Matches → Final Prediction → DB Save
ScraperService	scraper.service.ts	Mackolik HTML scraping: Cheerio ile data-settings ve window.dataLayer parse. Odds, lineup, stats, event çekimi

---

6. Zamanlanmış Görevler (src/tasks/)

Görev	Cron	Açıklama
DataFetcherTask.fetchLiveMatches()	*/15 * * * *	Mackolik API'den futbol maçlarını çek, live_matches tablosuna yaz. Top league filtresi
DataFetcherTask.fetchOddsForPreMatches()	*/15 * * * *	Başlamamış maçların oranlarını çek (futbol + basketbol). Retry logic (502/timeout)
DataFetcherTask.fetchBasketballMatches()	Manuel	Basketbol maçlarını çek. basketball_top_leagues.json filtresi
LiveUpdaterTask.updateLiveScores()	*/15 * * * *	Canlı maç skorlarını güncelle (Mackolik match-info API)
LiveUpdaterTask.finalizeFinishedMatches()	*/30 * * * *	Bitmiş maçları live_matches → matches tablosuna migrate et
LimitResetterTask.resetUsageLimits()	0 3 * * *	Günlük kullanım limitlerini sıfırla (03:00 Istanbul)
LimitResetterTask.cleanupOldData()	0 4 * * *	30 günlük AI logları sil, 1 günlük bitmiş live_matches sil
LimitResetterTask.checkSubscriptions()	0 0 * * *	Süresi dolmuş abonelikleri expired yap

---

7. AI Engine (Python/FastAPI) — ai-engine/

Bağımsız Python mikro servis. Default port: 8000.

7.1 Endpointler

Method	Endpoint	Açıklama
POST	/v20plus/analyze/{match_id}	Tekil maç analizi (ana endpoint)
GET	/v20plus/analyze-htms/{match_id}	İlk yarı - Maç sonu analizi
GET	/v20plus/analyze-htft/{match_id}	HT/FT olasılıkları (timeout destekli)
POST	/v20plus/coupon	Akıllı kupon üretimi (strateji + filtreleme)
GET	/v20plus/daily-banker	Günün banko maçları
GET	/v20plus/reversal-watchlist	Score reversal izleme listesi
GET	/health	Sağlık kontrolü

7.2 Mimari

ai-engine/
├── main.py                 # FastAPI app, route tanımları
├── services/
│   └── single_match_orchestrator.py  # V20+ ana orkestratör (singleton)
├── core/                   # Çekirdek algoritmalar
├── features/               # Feature engineering
├── models/                 # ML modelleri
├── training/               # Model eğitim scriptleri
├── config/                 # Konfigürasyon
├── utils/                  # Yardımcı fonksiyonlar
└── tests/                  # Test dosyaları

7.3 Tahmin Çıktı Yapısı (SingleMatchPredictionPackage)

{
  model_version: "v20plus.X",
  match_info: { match_id, match_name, home_team, away_team, league, match_date_ms },
  data_quality: { label: "HIGH"|"MEDIUM"|"LOW", score, flags, lineup_counts },
  risk: { level: "LOW"|"MEDIUM"|"HIGH"|"EXTREME", score, is_surprise_risk, warnings },
  engine_breakdown: { team, player, odds, referee },  // 4 motor ağırlığı
  main_pick: { market, pick, probability, confidence, odds, bet_grade, edge, ... },
  value_pick: { ... },
  bet_advice: { playable, suggested_stake_units, reason },
  bet_summary: [{ market, pick, raw_confidence, calibrated_confidence, bet_grade, ... }],
  supporting_picks: [...],
  aggressive_pick: { market, pick, probability, confidence, odds },
  scenario_top5: [{ score, prob }],
  score_prediction: { ft, ht, xg_home, xg_away, xg_total },
  market_board: { ... },
  reasoning_factors: ["..."],
  ai_commentary: "Gemini üretimi Türkçe yorum"
}

---

8. API Endpointleri (50 Toplam)

Auth (4 endpoint) — Public

Method	Path	Açıklama
POST	/api/auth/register	Kayıt ol
POST	/api/auth/login	Giriş yap
POST	/api/auth/refresh	Token yenile
POST	/api/auth/logout	Çıkış yap (refresh token invalid)

Users (5 endpoint) — Auth gerekli

Method	Path	Açıklama
GET	/api/users	Kullanıcı listesi
GET	/api/users/:id	Kullanıcı detay
PUT	/api/users/:id	Kullanıcı güncelle
POST	/api/users/:id/restore	Silinmiş kullanıcıyı geri al

Admin (11 endpoint) — Superadmin

Method	Path	Açıklama
GET	/api/admin/users	Tüm kullanıcılar (paginated)
GET	/api/admin/users/:id	Kullanıcı detay
PUT	/api/admin/users/:id/role	Rol değiştir
PUT	/api/admin/users/:id/subscription	Abonelik güncelle
PUT	/api/admin/users/:id/toggle-active	Aktif/Pasif toggle
DELETE	/api/admin/users/:id	Soft-delete
GET	/api/admin/settings	Tüm ayarlar
PUT	/api/admin/settings/:key	Ayar güncelle
GET	/api/admin/usage-limits	Kullanım limitleri
POST	/api/admin/usage-limits/reset-all	Toplu limit sıfırla
GET	/api/admin/analytics/overview	Sistem istatistikleri

Matches (4 endpoint) — Public

Method	Path	Açıklama
GET	/api/matches	Maç listesi (paginated)
POST	/api/matches/query	Gelişmiş maç sorgusu (filtreleme)
GET	/api/matches/leagues/active	Aktif ligler (cached 1dk)
GET	/api/matches/:id	Maç detayı (kadro, stat, oran, olaylar)

Leagues (8 endpoint) — Public

Method	Path	Açıklama
GET	/api/leagues	Tüm ligler
GET	/api/leagues/:id	Lig detay
GET	/api/leagues/countries	Ülke listesi
GET	/api/leagues/countries/:id	Ülke detay + ligleri
GET	/api/leagues/teams/search	Takım arama
GET	/api/leagues/teams/:id	Takım detay
GET	/api/leagues/teams/:id/matches	Takım son maçları
GET	/api/leagues/teams/h2h	Head-to-head

Analysis (2 endpoint) — Auth gerekli

Method	Path	Açıklama
POST	/api/analysis/analyze-matches	Çoklu maç analizi
GET	/api/analysis/history	Analiz geçmişi

Coupon (6 endpoint) — Mixed

Method	Path	Açıklama
POST	/api/coupon/analyze-match	Tekil maç analizi (V20) — Public
POST	/api/coupon/daily-banko	Günün bankosu (2 maç, %78+) — Public
POST	/api/coupon/suggest	Akıllı kupon öner (5 strateji) — Public
POST	/api/coupon/create	Kupon kaydet — Auth
GET	/api/coupon/my-stats	Kullanıcı istatistikleri — Auth
GET	/api/coupon/history	Kupon geçmişi — Auth

Predictions (7 endpoint) — Requires Redis

Method	Path	Açıklama
GET	/api/predictions/health	AI Engine health
GET	/api/predictions/upcoming	Yaklaşan tahminler
GET	/api/predictions/value-bets	EV+ fırsatları
GET	/api/predictions/history	Tahmin geçmişi & doğruluk
GET	/api/predictions/:matchId	Tekil maç tahmini (cached)
POST	/api/predictions/generate	Tahmin üret
POST	/api/predictions/smart-coupon	Smart Coupon (V20 AI)

Health (3 endpoint) — Public

Method	Path	Açıklama
GET	/api/health	Readiness
GET	/api/health/live	Liveness
GET	/api/health/detail	Detaylı sağlık

---

9. Common Layer (src/common/)

Dosya	Açıklama
base/base.service.ts	Generic BaseService (findAll, findOne, create, update, delete)
base/base.controller.ts	Generic BaseController (CRUD endpointleri)
decorators/index.ts	@Public(), @Roles(), @CurrentUser() decoratorları
dto/pagination.dto.ts	PaginationDto — page, limit, sortBy, sortOrder, search
filters/global-exception.filter.ts	GlobalExceptionFilter — HTTP 200 wrapper, dev stack trace, i18n error keys
interceptors/response.interceptor.ts	ResponseInterceptor — Standart API response wrapper
types/api-response.type.ts	ApiResponse<T>, createSuccessResponse(), createErrorResponse(), createPaginatedResponse()
queues/queue.module.ts	BullMQ module konfigürasyonu
utils/image.util.ts	Canvas yardımcı fonksiyonları

Standart API Response Formatı

{
  "success": true,
  "status": 200,
  "message": "Success",
  "data": { ... },
  "errors": []
}

---

10. Güvenlik & Guard Sistemi

Tüm guard'lar global olarak uygulanır (app.module.ts):

1. ThrottlerGuard — Rate limiting (default: 100 req/60s)
2. JwtAuthGuard — JWT token doğrulama (@Public() ile bypass)
3. RolesGuard — Rol tabanlı erişim (@Roles('superadmin'))
4. PermissionsGuard — İzin tabanlı erişim kontrolü

Password: bcrypt, 12 salt rounds
Token: JWT Access (15dk) + UUID Refresh Token (7 gün, DB'de saklanır)

---

11. Veri Akış Diyagramları

11.1 Canlı Maç Veri Akışı

Mackolik API (her 15dk)
      │
      ▼
DataFetcherTask.fetchLiveMatches()
      │
      ├─→ Country upsert
      ├─→ League upsert  
      ├─→ Team upsert (home + away)
      └─→ LiveMatch upsert (top_leagues.json filtresi)
      
      │ (her 15dk)
      ▼
DataFetcherTask.fetchOddsForPreMatches()
      │
      └─→ LiveMatch.odds (JSON) + oddsUpdatedAt güncelle

      │ (her 15dk)
      ▼
LiveUpdaterTask.updateLiveScores()
      │
      └─→ LiveMatch score/state güncelle

      │ (her 30dk)
      ▼
LiveUpdaterTask.finalizeFinishedMatches()
      │
      └─→ LiveMatch → Match tablosuna migrate

11.2 Tahmin İstek Akışı

Client POST /api/coupon/analyze-match
      │
      ▼
SmartCouponService.analyzeMatch(matchId)
      │
      ├─→ AI Engine POST /v20plus/analyze/{matchId}
      │         │
      │         └─→ SingleMatchOrchestrator.analyze_match()
      │                    │
      │                    └─→ DB'den veri çek → ML modeli → Tahmin paketi
      │
      ├─→ GeminiService.generateText() (commentary, Türkçe)
      │
      └─→ SingleMatchPredictionPackage döndür

---

12. Konfigürasyon

Environment Variables

Değişken	Açıklama	Default
NODE_ENV	Ortam	development
PORT	Sunucu portu	3005
DATABASE_URL	PostgreSQL bağlantısı	—
JWT_SECRET	JWT imza anahtarı	—
JWT_ACCESS_EXPIRATION	Access token süresi	15m
JWT_REFRESH_EXPIRATION	Refresh token süresi	7d
REDIS_ENABLED	Redis/BullMQ aktif mi	false
REDIS_HOST	Redis host	localhost
REDIS_PORT	Redis port	6379
AI_ENGINE_URL	Python AI Engine URL	http://127.0.0.1:8000
ENABLE_GEMINI	Gemini AI aktif mi	false
GOOGLE_API_KEY	Gemini API anahtarı	—

Config Dosyaları

Dosya	Açıklama
top_leagues.json	Futbol top lig ID'leri (canlı maç filtresi)
basketball_top_leagues.json	Basketbol top lig ID'leri
src/config/configuration.ts	NestJS config factory'leri
src/config/env.validation.ts	Zod ile env doğrulama

---

13. Build & Run Komutları

# Development
npm run start:dev          # NestJS watch mode (port 3005)

# Production
npm run build && npm run start:prod

# Feeder (Data Collection)
npm run feeder:historical  # Tarihsel veri taraması (2023-06→bugün)
npm run feeder:fill-gaps   # Eksik veri tamamlama
npm run feeder:basketball  # Basketbol verisi
npm run feeder:live        # Canlı veri

# Database
npx prisma generate        # Prisma client güncelle
npx prisma migrate dev     # Migration çalıştır
npx prisma db seed          # Seed data

# Testing
npm run test               # Unit testler
npm run test:e2e           # E2E testler

# AI Engine (Python)
cd ai-engine && uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Swagger
npm run swagger:summary    # Endpoint export

---

14. Docker Deployment

# docker-compose.yml (3 servis)
services:
  backend:     # NestJS (port 3005)
  ai-engine:   # Python FastAPI (port 8000)
  postgres:    # PostgreSQL 16 (port 5432)
  redis:       # Redis (opsiyonel, port 6379)

---

15. Bilinen Durumlar ve Notlar

1. Predictions modülü Redis gerektirir (REDIS_ENABLED=true). Redis yoksa bu modül yüklenmez.
2. Gemini AI opsiyoneldir. Devre dışıyken maç yorumu null döner.
3. Feeder V17 AI feature hesaplama devre dışı bırakılmıştır — V20 modeli Python tarafında çalışır.
4. Lineup scraping V20 optimizasyonu için devre dışıdır — sadece Team Stats kullanılır.
5. Global Exception Filter tüm hataları HTTP 200 olarak döner, gerçek status body içindedir.
6. Abonelik sistemi Free/Active/Expired — Free: 10 analiz + 3 kupon/gün, Active: 50 + 10.
7. Veri kaynağı tek: Mackolik.com — hem canlı API hem HTML scraping.
8. Social Poster Twitter API v2 ile çalışır, Instagram/Meta henüz implemente edilmemiştir.

---

16. Canlı Veritabanı Analizi (MCP ile PostgreSQL Sorguları)

Aşağıdaki veriler 2026-03-12 tarihinde canlı veritabanından çekilmiştir.

16.1 Genel İstatistikler

Metrik	Değer
Toplam DB Boyutu	3,658 MB (3.6 GB)
Toplam Tablo	27
Veri Aralığı	2023-06-01 → 2026-03-12

16.2 Tablo Boyutları (Büyükten Küçüğe)

Tablo	Kayıt Sayısı	Toplam Boyut	Veri	Index
odd_selections	8,511,132	1,070 MB	543 MB	526 MB
match_player_participation	3,342,839	1,077 MB	430 MB	648 MB
odd_categories	3,161,172	689 MB	294 MB	394 MB
match_player_events	1,453,227	356 MB	239 MB	117 MB
match_player_stats	344,688	120 MB	60 MB	60 MB
match_team_stats	310,991	91 MB	37 MB	54 MB
match_officials	340,824	75 MB	29 MB	47 MB
matches	236,859	100 MB	60 MB	40 MB
players	217,040	64 MB	26 MB	37 MB
teams	19,595	5.2 MB	—	—
leagues	1,505	760 KB	—	—
live_matches	82	1 MB	—	—
countries	160	120 KB	—	—
match_ai_features	279	152 KB	—	—
predictions	3	192 KB	—	—
users	1	80 KB	—	—
refresh_tokens	8	80 KB	—	—
usage_limits	1	80 KB	—	—
app_settings	3	64 KB	—	—
official_roles	5	48 KB	—	—
translations	0	48 KB	—	—
analyses	0	32 KB	—	—
odds_history	0	32 KB	—	—
user_coupons	0	32 KB	—	—
ai_predictions_log	0	32 KB	—	—
user_coupon_items	0	24 KB	—	—

16.3 Spor Bazlı Dağılım

Spor	Maç Sayısı	Lig Sayısı	Takım (~)	Ort. Ev Skoru	Ort. Deplasman Skoru
Futbol	189,291	1,094	~23,958	1.55	1.27
Basketbol	47,568	304	~5,770	84.36	81.57

16.4 Maç Olayları Dağılımı

Olay Tipi	Toplam
substitute (Oyuncu Değişikliği)	787,101
card (Kart)	409,136
goal (Gol)	256,990

16.5 Canlı Maçlar (live_matches — 82 Kayıt)

Spor	Durum	Status	Sayı
Futbol	pre (başlamamış)	timestamp	41
Futbol	post (bitmiş)	state	4
Futbol	live (canlı)	minutes	1
Basketbol	pre (başlamamış)	timestamp	23
Basketbol	post (bitmiş)	state	13

16.6 Türkiye Ligleri (En Çok Maç)

Lig	Maç Sayısı
Nesine 3. Lig	1,511
Nesine 2. Lig	1,295
Trendyol 1. Lig	988
Trendyol Süper Lig	959
Türkiye Sigorta BSL (Basketbol)	637
Türkiye Sigorta TBL (Basketbol)	450
Ziraat Türkiye Kupası	438
Halkbank KBSL (Kadınlar Basketbol)	436
Halkbank Kadınlar Basketbol 1.Ligi	383

16.7 Global Top 10 Lig (En Çok Maç)

Lig	Ülke	Maç
Segunda Lig RFEF	İspanya	3,848
Non Lig Premier	İngiltere	3,553
NBA	ABD	3,529
Bölgesel Lig	Almanya	3,457
Hazırlık Maçları	Dünya	3,454
Serie C	İtalya	2,923
Ulusal Lig N/S	İngiltere	2,843
RFEF 3. Lig	İspanya	2,297
2. Lig	İsveç	2,202
3. Lig	Norveç	2,188

16.8 Feeder Scan Durumu (app_settings)

Scan Job	Son İşlenen Tarih	Güncelleme
historical_scan_state_football_basketball	2026-03-11	2026-03-11 21:03
historical_scan_state_football_filtered_desc	2025-09-01	2026-02-26 09:27
historical_scan_state_football_filtered	2023-10-16	2026-02-12 18:03

16.9 Kullanıcı Durumu

Metrik	Değer
Toplam kullanıcı	1 (test@test.com)
Rol	user
Abonelik	free
Kayıt tarihi	2026-02-09
Aktif kupon	0
Analiz geçmişi	0

16.10 Hakem Rolleri

ID	Rol
1	Orta Hakem
2	Yardımcı Hakem
3	4. Hakem
4	VAR
5	AVAR

16.11 Boş/Kullanılmamış Tablolar

Aşağıdaki tablolar henüz production verisine sahip değildir:

• translations — DB tabanlı i18n (dosya tabanlı i18n kullanılıyor)
• analyses — Kullanıcı analiz kayıtları (kullanıcı yok)
• odds_history — Oran değişim takibi (henüz implemente edilmemiş)
• user_coupons / user_coupon_items — Kullanıcı kuponları (kullanıcı yok)
• ai_predictions_log — AI tahmin loglama (cleanup job siliyor veya henüz üretilmemiş)