iddaai-be/project_summary.md

# Backend Project Summary

## 1. Bu backend ne yapiyor?

Bu backend, spor bahis tahmini ve karar destek sistemi olarak tasarlanmis bir NestJS uygulamasidir. Uygulama yalnizca mac listeleyen bir servis degildir; asil isi su zinciri yonetmektir:

1. Dis kaynaklardan mac, oran, kadro, hakem, eksik oyuncu ve sonuc verilerini toplamak.
2. Bu verileri normalize edip veritabanina yazmak.
3. Python tabanli AI motoruna uygun veri yuzeyi sunmak.
4. Tek mac tahmini, value bet, kupon onerisi ve Spor Toto uretilmis ciktilarini API olarak vermek.
5. Kimlik dogrulama, kullanici limitleri, kullanici kuponlari ve yonetimsel ekranlari desteklemek.

Projenin pratikteki urun kimligi "sports betting intelligence backend" olarak okunmali.

## 2. Teknoloji omurgasi

- Framework: NestJS 11
- ORM: Prisma
- Veritabani: PostgreSQL varsayimi ile tasarlanmis Prisma semasi
- Queue/async: BullMQ + Redis opsiyonel
- Scheduler: `@nestjs/schedule`
- AI entegrasyonu: Harici Python/FastAPI servis cagrilari
- Auth: JWT access token + refresh token
- Dokumantasyon: Swagger
- I18n: `nestjs-i18n`

Temel giris dosyalari:

- `src/main.ts`: uygulamayi ayaga kaldirir, global filter/interceptor/validation ayarlarini yapar.
- `src/app.module.ts`: tum modulleri birlestirir, feeder/schedule/queue davranislarini ortam degiskenlerine gore sekillendirir.
- `src/config/configuration.ts` ve `src/config/env.validation.ts`: env tabanli konfigurasyon.

## 3. Mimariyi nasil okumali?

Backend mantigi 4 ana katmanda okunmali:

### A. Domain API katmani

Kullanicinin ya da frontend'in gordugu endpointler burada:

- `auth`
- `users`
- `admin`
- `matches`
- `leagues`
- `predictions`
- `coupons`
- `analysis`
- `spor-toto`
- `health`

### B. Veri toplama ve veri isleme katmani

Burasi urunun can damari:

- `feeder` modulu
- `data-fetcher.task.ts`
- `historical-results-sync.task.ts`
- `limit-resetter.task.ts`
- scraper/transformer/persistence servisleri

Bu katman yoksa tahmin urunu deger kaybeder, cunku AI motorunun beslendigi veri bu katmanda toplanir.

### C. AI entegrasyon katmani

Backend kendi basina tum modellemeyi yapmaz. Temel strateji:

- Match verisini uygun hale getir
- Gerekli cache ve validasyon kontrolunu yap
- Python AI servisini cagir
- Gelen cevabi urun dostu response'a cevir

Bu akis en cok `predictions` ve `smart-coupon` tarafinda gorulur.

### D. Kullanici / urun operasyon katmani

Burada kimlik, limit, kullanici kuponlari, admin ekranlari ve bazi raporlama taraflari vardir.

## 4. Uygulamanin davranis ozellikleri

### 4.1 Response standardizasyonu

Backend klasik REST semantigini tam anlamiyla izlemiyor. Basarili cevaplar global response interceptor ile benzer bir yapida donuyor:

```json
{
  "success": true,
  "status": 200,
  "message": "...",
  "data": {}
}
```

Hata akisi da global exception filter ile sarmalaniyor. Dikkat edilmesi gereken nokta su: bazi hatalar HTTP seviyesinde 4xx/5xx yerine govdede `success: false` ve `status` ile temsil ediliyor. Frontend'in `create-api-client` katmani da bu yuzden yalnizca HTTP status'e degil response body'ye bakiyor.

### 4.2 Global auth / role / permission yaklasimi

`AppModule` icinde guard'lar global duzeyde baglanmis. Yani endpoint korumasi per-controller bazli tek tek degil, merkezi sekilde uygulanmis. JWT strategy ile kullanici context'i request'e ekleniyor.

### 4.3 Queue opsiyonel davranis

Prediction isleri Redis/BullMQ ile queue'lanabilir; fakat queue altyapisi kapalisa backend dogrudan AI servisini cagirabilir. Bu, lokal gelistirme ve daha basit deployment senaryolari icin esneklik sagliyor.

## 5. Veritabani modeli: projenin asil haritasi

En kritik dosya `prisma/schema.prisma`. Buradaki modeli anlamadan backend'i tam anlamak zor.

### 5.1 Cekirdek spor varliklari

- `Country`
- `League`
- `Team`
- `Player`
- `Match`
- `LiveMatch`

Buradaki en onemli fikir:

- `LiveMatch`: anlik, operasyonel, browse edilen, guncel mac yuzeyi
- `Match`: daha kalici, tarihsel, detayli kayit

Bu iki tablo ayni seyi tekrar etmiyor; farkli amaclara hizmet ediyor.

### 5.2 Mac detay ve istatistik ekosistemi

Semada futbol ve basketbol ayrimi belirgin:

- takim istatistikleri
- oyuncu istatistikleri
- oyuncu katilimlari
- event kayitlari
- official / referee rolleri
- odds history ve odds selection yapilari

Bu veri modeli, yalnizca skor saklamak degil; model feature uretimine uygun detay yakalamak icin kurulmus.

### 5.3 AI ve prediction tarafi

- `football_ai_features`
- `basketball_ai_features`
- `team_elo_ratings`
- `predictions`
- `ai_predictions_log`

Bu taraf, AI cevabini yalnizca gecici tutmuyor; cache, audit ve yeniden kullanim katmani da olusturuyor.

### 5.4 Kullanici urunu tarafi

- `users`
- `refresh_tokens`
- `usage_limits`
- `analyses`
- `user_coupons`
- `user_coupon_items`

Bu, urunun salt "tahmin motoru" olmayip kullanici tabanli SaaS urune dogru evrildigini gosteriyor.

### 5.5 Spor Toto domain'i

- `toto_bulletins`
- `toto_bulletin_matches`
- `toto_results`
- `toto_coupons`
- `toto_columns`

Bu kisim, sistemin normal match prediction hattindan ayri ama ona paralel bir urun cizgisi.

## 6. Ana moduller ve rolleri

### 6.1 `auth`

Giris, kayit, refresh, logout. JWT tabanli. Refresh token veritabaninda tutuluyor. Frontend NextAuth credentials akisi bunu tuketiyor.

### 6.2 `users`

Kullanici profili, sifre guncelleme, kendi bilgilerini cekme ve kullaniciya ait bazi istatistikler. Bu modul, kullanici urun tarafinin merkezlerinden biri.

### 6.3 `admin`

Admin analytics ve kullanici listeleri gibi yonetimsel endpointler var. Frontend'de admin content ekranina veri sagliyor.

### 6.4 `matches`

Backend'in browse katmani. Genellikle aktif / upcoming / live maclari `live_matches` uzerinden verir. Mac detayinda bazen `matches` tablosuna, bazen fallback ile `live_matches` tablosuna bakar.

Bu modul kullanicinin "sistemde su an ne var?" sorusuna cevap verir.

### 6.5 `leagues`

Ligler, ulkeler, takim arama, bazi h2h veya takim merkezli look-up akislarini besler.

### 6.6 `predictions`

Modern AI prediction hattinin merkezi moduludur.

Yaptigi ana isler:

1. Match uygun mu kontrol et.
2. Gerekli veri var mi bak.
3. Cache'de gecerli prediction var mi kontrol et.
4. Yoksa AI motorunu cagir.
5. Gelen cevabi frontend'in kullanacagi zengin response'a cevir.

Burada tek bir "winner" alani yok; confidence, signal, edge, playable/not playable gibi karar destegi unsurlari da uretilir.

### 6.7 `coupons`

Iki farkli damar gorunuyor:

- daha eski veya daha basit kupon servis mantigi
- asil AI destekli akis: `smart-coupon.service.ts`

`SmartCouponService` kullaniciya strateji bazli kupon olusturmak icin AI motoruna gider. Ayrica bazi yorum/icerik zenginlestirme taraflarinda Gemini benzeri servislerle entegrasyon izi var.

Kullanici kupon kayitlari ise ayri bir servisle veritabanina yazilir ve basit settlement mantigi ile sonradan sonuclandirilabilir.

### 6.8 `analysis`

Bu taraf daha legacy gorunuyor. Akis su tipte:

- URL veya match bazli girdi al
- scraping veya veri cekme yap
- AI cagrisi yap
- sonucu `analyses` tablosuna kaydet

Yeni prediction hattina gore daha eski jenerasyon bir urun parcasi gibi duruyor.

### 6.9 `spor-toto`

Projenin en ayri domainlerinden biri.

Sadece mac tahmini yapmak yerine:

- resmi bultenleri senkronize eder
- 15 maclik Toto veri modelini tutar
- sistem/kolon mantigi ile kupon uretir
- sonuc degerlendirir
- rollover ve istatistik sunar

Bu modul kendi basina yari-ayri urun gibi dusunulebilir.

### 6.10 `feeder`

Dis veri akisinin duzeni burada. Bu modul:

- dis kaynak verisini toplar
- donusturur
- normalize eder
- kaydeder
- bazen medya/logo indirir

Prediction kalitesinin tabani buradadir.

## 7. Veri toplama akislari

### 7.1 Canli ve guncel veri toplama

`data-fetcher.task.ts` belirli araliklarla calisir ve sunlari yapar:

- mac listesini yeniler
- canli skor gunceller
- oran ceker
- hakem/kadro/eksik oyuncu datasi toplar
- bazi eksik alanlari tamamlamaya calisir

Pratikte "uygulamada bugun ne var?" sorusunu bu task besler.

### 7.2 Tarihsel sync

`historical-results-sync.task.ts`, tamamlanmis maclari tarihsel ana tablolara tasir ve uzun vadeli feature / history / analysis ihtiyacini destekler.

### 7.3 Limit ve bakim gorevleri

`limit-resetter.task.ts`:

- kullanim limitlerini resetler
- eski verileri temizler
- gerekli periyodik bakim islerini yapar

### 7.4 Historical feeder modu

`FEEDER_MODE=historical` gibi davranislar ile uygulama schedule/queue davranisini degistirebilir. Bu, backfill ve buyuk tarihsel veri yukleme senaryolari icin dusunulmus.

## 8. Veri kaynagi ve persistence mantigi

Feeder'in persistence katmani sadece `match` satiri yazmaz. Genel akil:

1. Ulkeyi bul veya olustur.
2. Ligi bul veya olustur.
3. Takimlari bul veya olustur.
4. Mac kaydini upsert et.
5. Oyunculari ve katilimlarini yaz.
6. Event / istatistik / odds verisini kaydet.
7. Gerekirse logolari indir ve storage/public altina al.

Bu nedenle sistemin veri modeli oldukca "sports data warehouse" tarzi okunabilir.

## 9. AI entegrasyonu gercekte nasil calisiyor?

Backend tarafi tek basina model calistirmiyor; Python motorunu tuketiyor.

Temel endpoint ailesi:

- tek mac analiz
- kupon olusturma
- daily banker benzeri guvenli secim uretimi
- bazi ozel market/htft/reversal benzeri analizler
- health check

Prediction servisinde cagin fark yaratan kisimlar:

- stale/valid prediction cache kontrolu
- model versiyon kontrolu
- odds mevcut mu kontrolu
- AI cevabini urun diline cevirmek
- translation/reason enrichment
- playable market secimi

Yani backend, AI motoru ile frontend arasinda yalnizca proxy degil; is mantigi katmanidir.

## 10. Python AI motorunun backend acisindan anlami

Repo icindeki `ai-engine` klasoru teknik olarak ayrik servis olsa da urun acisindan backend'in uzantisidir.

Orchestrator tarafinda sunlar birlestiriliyor:

- match metadata
- odds ve implied probability
- lineup/availability quality
- league reliability
- model ensemble signal'lari
- risk katmanlari
- confidence calibration
- stake / Kelly benzeri kararlar

Sonuc olarak sadece "MS1" degil; kullanilabilirlik ve edge mantigi uretiliyor.

Bu nedenle bu proje klasik tahmin API'sinden daha cok "bet selection engine" gibi davranir.

## 11. Kullanici kuponlari

Kullanici kuponlarinin iki farkli yuzeyi var:

- AI'nin onerdigi akilli kupon
- kullanicinin kendi sectigi kuponu kaydetme / listeleme / settlement

Settlement mantigi tam bir odds engine kadar derin degil; bazi marketlerde string ve temel score karsilastirmalari ile sonuclandirma yapildigi gorunuyor. Bu kisim prod icin yeterli olabilir ama her market turu icin evrensel bir settlement motoru degil.

## 12. Swagger ve endpoint yuzeyi

Projede endpoint ozet export scriptleri ve swagger summary dosyalari var. Bu da ekibin API yuzeyini en azindan belgelemeye calistigini gosteriyor.

Ana endpoint aileleri:

- `/auth/*`
- `/users/*`
- `/admin/*`
- `/matches/*`
- `/leagues/*`
- `/predictions/*`
- `/coupons/*`
- `/analysis/*`
- `/spor-toto/*`
- `/health`

Bu endpoint ailesi backend'in urun sinirlarini da iyi anlatiyor.

## 13. Dikkat edilmesi gereken tasarim kararlari ve tutarsizliklar

Bu kisim "bug listesi" degil; repo'yu okuyacak AI icin gercek durum notudur.

### 13.1 HTTP 200 ile hata donme davranisi

Client tarafinda normal REST beklentisi kurulmamalidir. Body-level status kontrolu gerekir.

### 13.2 `live_matches` ve `matches` ayrimi cok onemli

Bu ayrimi kaciran biri backend'i yanlis okur. Tum endpointler ayni kaynaktan beslenmez.

### 13.3 Legacy ve modern prediction akislari birlikte yasiyor

`analysis` daha eski, `predictions` + `smart coupon` daha yeni omurga gibi duruyor.

### 13.4 Soft delete katmani ile schema birebir ortusmuyor olabilir

Prisma service tarafinda daha genel bir soft delete dusuncesi var ama schema tarafinda bunun her modelde ayni derinlikte uygulanmadigi izlenimi var.

### 13.5 Queue altyapisi zorunlu degil

Sistem Redis olmadan da belli modlarda calisabilecek sekilde esnetilmis.

## 14. Bu backend'i en dogru nasil zihinde tutmali?

Asagidaki cumle projeyi en iyi ozetler:

Bu backend, spor verisi toplayan, bunu normalize eden, tarihsel ve canli veri katmanlarini ayiran, AI tabanli bahis karar destek ciktilarini cache'leyip urunlestiren, bunun ustune kupon ve Spor Toto deneyimleri kuran bir NestJS platformudur.

## 15. AI veya yeni gelisen ekip arkadasi icin kisa okuma sirasi

Bu repo'yu yeni okuyan biri icin en verimli sira:

1. `README.md`
2. `prompt.md`
3. `prisma/schema.prisma`
4. `src/app.module.ts`
5. `src/modules/matches/*`
6. `src/modules/predictions/*`
7. `src/modules/coupons/services/smart-coupon.service.ts`
8. `src/modules/spor-toto/*`
9. `src/modules/feeder/*`
10. `src/tasks/*`
11. `ai-engine/main.py`
12. `ai-engine/services/single_match_orchestrator.py`

## 16. Son soz

Bu backend'in asil degeri CRUD endpointlerinden degil, su bilesimden gelir:

- veri toplama kalitesi
- veri modeli derinligi
- AI entegrasyon orkestra mantigi
- urunlestirilmis prediction/coupon/toto akislari

Bir AI bu repo'yu anlayacaksa, bu projeyi "NestJS API" olarak degil "sports betting intelligence platform backend" olarak okumali.