first (part 1: root files)

project_summary.md

@@ -0,0 +1,789 @@
+# 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)
+
+```typescript
+{
+  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<T> (findAll, findOne, create, update, delete) |
+| `base/base.controller.ts` | Generic BaseController<T> (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ı
+
+```json
+{
+  "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ı
+
+```bash
+# 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
+
+```yaml
+# 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ş)