iddaai-fe/project_summary.md

Frontend Project Summary

1. Bu frontend ne yapiyor?

Bu frontend, backend ve AI motorunun urettigi spor bahis istihbaratini son kullanici urunune ceviren Next.js uygulamasidir. Gorevi sadece veri gostermek degildir; kullaniciyi su urun akislarina sokar:

• maclari ve ligleri kesfetme
• tek mac detay ve AI tahminini gorme
• upcoming predictions ve value bet yuzeylerini tuketme
• AI destekli kupon uretme
• kullanici kuponlarini kaydetme / inceleme
• Spor Toto bultenlerinden sistem kuponu uretme
• profil, auth ve dashboard deneyimini yonetme

Bu nedenle frontend, "sports betting dashboard + decision UI" gibi dusunulmeli.

2. Teknoloji omurgasi

• Framework: Next.js 16 App Router
• UI: Chakra UI v3
• State/server cache: TanStack React Query
• Local state: Zustand
• Auth: NextAuth credentials akisi
• I18n: next-intl
• Motion: framer-motion + aos

Temel amac, backend'den gelen AI zengin response'lari urune ceviren modern bir dashboard/site yapisi kurmak.

3. Genel mimari

Frontend'i 5 katmanda okumak mantikli:

A. Routing ve app shell

src/app/[locale] altindaki route yapisi, locale-prefix zorunlu bir App Router kurgusu kullaniyor. Uygulamada tr ve en mantigi bulunuyor.

B. Provider ve global uygulama katmani

src/components/ui/provider.tsx tarafinda:

• SessionProvider
• Chakra provider
• React Query provider
• animation/top loader/toaster

gibi global baglamlar olusturuluyor.

C. API client katmani

Frontend, backend ile dogrudan her komponentte konusmuyor. Bunun yerine:

• src/lib/api/create-api-client.ts
• src/lib/api/api-service.ts
• ilgili domain service/hook dosyalari

uzerinden iletisim kuruyor.

D. Domain ekranlari

Asil urun ekranlari:

• home
• matches
• match detail
• predictions
• coupon builder
• coupon history
• analysis
• spor toto
• dashboard
• profile
• admin

E. Client-side state

Zustand store'lari ile secili maclar, filtreler ve kupon builder state'i elde tutuluyor.

4. Route mantigi ve sayfa yapisi

4.1 Locale-first routing

Tum sayfalar src/app/[locale] altinda konumlanmis. Bu, URL yapisinin /tr/... veya /en/... olmasi gerektigini gosteriyor.

4.2 Site ve auth ayrimi

Routing yapisinda iki ana grup var:

• (auth): signin, signup gibi auth ekranlari
• (site): asil urun ekranlari

Bu ayrim layout seviyesinde de yapilmis; yani login/register deneyimi ile urun shell'i birbirinden ayriliyor.

4.3 Ana kullanici yuzeyleri

Onemli sayfalar:

• home: urunun tanitim ve giris noktasi
• matches: mac kesfi
• matches/[id]: tek mac detay ve prediction
• predictions: upcoming/value/history
• coupon-builder: AI destekli kupon olusturma
• spor-toto: Toto deneyimi

Bu sayfalar projenin asil urun omurgasini olusturuyor.

5. API ile konusma mantigi

5.1 API client'in onemi

createApiClient katmani frontend'in en onemli altyapilarindan biri. Burada:

• token otomatik eklenir
• Accept-Language gonderilir
• response body'deki success/status kontrol edilir
• 401 benzeri durumlarda logout/redirect davranisi uygulanabilir

Bu katman cok onemli, cunku backend bazen klasik HTTP hata semantigi yerine body-level durum donuyor.

5.2 Domain service yapisi

Her buyuk domain icin genelde su pattern var:

• service.ts
• types.ts
• use-hooks.ts

Bu pattern su alanlarda goruluyor:

• matches
• predictions
• coupons
• analysis
• spor-toto
• users
• admin
• leagues

Yani veri cekme mantigi komponentlerden ayrilmaya calisilmis.

6. Auth mantigi

6.1 NextAuth credentials akisi

Frontend auth deneyimi NextAuth ile yonetiliyor. Ancak burada OAuth agirlikli bir kurgu degil, backend'in kendi /auth/* endpointlerini kullanan credentials akisi var.

6.2 Backend bagimliligi

Auth ekranlari backend response formatina ciddi sekilde bagimli. Login/register sonrasi access token ve kullanici bilgileri session'a tasiniyor.

6.3 Dikkat cekici nokta

Kodda src/lib/api/example/auth/service.ts gibi "example" koklu bir auth servis yolu kullaniliyor. Bu, projede bir noktada boilerplate veya scaffold'tan evrim gecisi oldugunu gosteriyor. Uygulama gercekte backend auth endpointleriyle konusuyor ama isimlendirme tarafinda kalinti izler var.

7. Ana ekranlar ve urun rolleri

7.1 Home

home-content.tsx, landing page / urun tanitim sayfasi gibi calisiyor. Kullaniciya platformun vaadini, ozelliklerini ve yonlendirmelerini sunuyor. Bu sayfa operasyonel ekran degil; urunun vitrini.

7.2 Matches

matches-content.tsx, aktif ve upcoming maclari kesfetme ekrani. Lig bazli filtreleme, spor secimi ve yan panel benzeri yapilarla kullaniciya mac havuzu sunuyor.

Bu ekran backend'deki live_matches mantiginin frontend karsiligidir.

7.3 Match Detail

match-detail-content.tsx en onemli ekranlardan biri. Burada:

• mac bilgisi
• oranlar
• AI prediction
• yardimci market / confidence benzeri katmanlar

kullaniciya tek bir detay sayfasinda sunulur.

Urunun "tek maca odakli karar verme" deneyimi burada yasar.

7.4 Predictions

predictions-content.tsx, backend prediction yuzeylerini toplu urune cevirir:

• upcoming predictions
• value bets
• gecmis / history benzeri alanlar

Bu ekran, tek mac yerine "bugun sistem ne oneriyor?" sorusuna cevap verir.

7.5 Coupon Builder

coupon-builder-content.tsx frontend'in en stratejik ekranlarindan biridir.

Bu ekranin ana akisi:

1. Kullanici uygun maclari gorur.
2. Mac secer veya strateji belirler.
3. Kupon tipi / risk stratejisi secilir.
4. Backend uzerinden AI kupon onerisi alinir.
5. Sonuc store'a yazilir ve kullanici duzenleyebilir.

Bu ekran, projenin "AI ile kupon olusturma" vaadini gercege cevirir.

Koddan anlasilan bir detay: tamamlanmis maclar bazen referans amacli okunuyor ama secilebilir kupon yuzeyinden ayriliyor. Bu, veri kaynagi ve UI ayrimi acisindan mantikli.

7.6 Coupon History

coupon-history-content.tsx, kullanicinin onceki kuponlarini gostermeyi amaclar. Ancak backend tarafinda history akislarinin bazilarinin stub/eksik oldugu izlenimi var; dolayisiyla bu ekranin veri derinligi backend ile birlikte degerlendirilmelidir.

7.7 Spor Toto

spor-toto-content.tsx, frontend'in ayri urun kimligine sahip ekranlarindan biri.

Burada:

• bulten secimi
• strateji secimi
• bulten sync tetikleme
• kolon / tahmin / Toto odakli sonuc gosterimi

yer alir.

Bu ekran normal mac prediction ekranindan farkli bir zihinsel model ister.

7.8 Analysis

analysis-content.tsx, daha eski urun katmaninin frontend yuzeyi gibi duruyor. Birden fazla mac veya farkli analiz girdi tipleri ile backend analysis modulune gider. Mevcut repo'da ana omurgadan biraz daha kenarda.

7.9 Dashboard

dashboard-content.tsx, kullaniciya bugunun maclari, ozet prediction yuzeyleri ve bazi kullanici istatistiklerini tek yerde toplar. Urunun "kontrol paneli" gibi davranir.

7.10 Profile

profile-content.tsx, session verisi ile kullanici servislerini birlestirir; profil ve sifre guncelleme gibi akislarin UI tarafidir.

7.11 Admin

admin-content.tsx, admin analytics ve kullanici listesini gosterir. Burada frontend'in backend admin endpointlerine baglandigi goruluyor. Ancak rol isimleri ve gorunurluk kontrolu tarafinda backend ile tam uyum konusu tekrar kontrol edilmelidir.

8. UI komponent mantigi

Frontend iki tip komponentten olusuyor:

A. Urun komponentleri

Bunlar is mantigi tasir:

• matches
• predictions
• coupons
• spor-toto
• dashboard
• profile
• admin

B. Design system / wrapper komponentleri

src/components/ui altinda cok sayida Chakra wrapper ve tekrar kullanilabilir UI parcasi var. Bunlar tasarim/ergonomi icin onemli ama urunun asil domain mantigini tasimiyor.

Bir AI repo'yu anlamaya calisirken bu iki katmani karistirmamali; asil davranis urun komponentleri ve src/lib/api tarafinda yasar.

9. State yonetimi

9.1 React Query

Sunucu verisi cache'lenir, refetch edilir ve async lifecycle burada yonetilir. Domain hook'lari bu sistemin ustune kurulmus.

9.2 Zustand

Iki anlamli local state merkezi gorunuyor:

• coupon-store: secili kupon / strateji / user interaction state
• match-store: spor ve lig filtre state'i

Bu secim mantikli; server state ile saf UI/domain interaction state ayrilmis.

10. I18n ve navigation

next-intl temelli bir locale sistemi kurulmus. Navigation katmani da locale-aware. Bu su anlama gelir:

• route helper'lari dil farkindaligina sahip
• metinler translation namespace'leri ile cekiliyor
• arayuz ilk gunden iki dillilik dusunulerek kurgulanmis

Bu, urunun uluslararasilasma niyeti oldugunu gosteriyor.

11. Backend ile baglantinin urunsel anlami

Frontend'in cogu ekrani backend'in asagidaki endpoint ailelerine yaslanir:

• auth
• users
• admin
• matches
• leagues
• predictions
• coupons
• analysis
• spor-toto

Yani frontend, tek bir "feed" ekrani degil; backend'deki tum ana domainlere UI saglayan bir cok-urun kabugudur.

12. Dikkat edilmesi gereken gercek durum notlari

Bu kisim "elestiri listesi" degil; repo'yu anlayacak AI icin baglam notudur.

12.1 FE/BE response kontratlari her yerde tam oturmuyor

Bazi type tanimlari ve hook beklentileri, backend'in fiili cevabiyla birebir eslesmeyebilir. Ornek olarak istatistik alanlari, coupon history veya bazi admin/user response'lari tekrar kontrol edilmelidir.

12.2 Stub/legacy izleri var

Ozellikle coupon history, analysis ve bazi auth/admin naming alanlarinda "tamamlanmis urun" ile "evrim gecirmis scaffold" arasi bir durum hissediliyor.

12.3 Rol isimleri ve admin gorunurlugu hassas konu

Header veya admin kontrolu tarafinda ADMIN gibi sabitler kullanilirken backend rol isimlendirmesi baska olabilir. Bu, UI gorunurlugunde sessiz hata uretebilir.

12.4 Global search ve bazi UI metinlerinde encoding kalintilari gorunuyor

Bu, repo'da karakter kodlamasi veya eski kopyalama izleri oldugunu gosteriyor; ana urun mantigi degil ama kalite notu olarak onemli.

13. Bu frontend'i zihinde nasil tutmali?

En dogru ozet su:

Bu frontend, spor verisi ve AI prediction ciktilarini kullaniciya karar verilebilir, karsilastirilabilir ve kupona donusturulebilir bir urun deneyimi olarak sunan locale-aware Next.js dashboard/site uygulamasidir.

14. Repo'yu anlayacak AI icin okuma sirasi

1. README.md
2. prompt.md
3. src/app/[locale]/layout.tsx
4. src/components/ui/provider.tsx
5. src/lib/api/create-api-client.ts
6. src/lib/api/*/service.ts
7. src/components/matches/*
8. src/components/predictions/*
9. src/components/coupons/coupon-builder-content.tsx
10. src/components/spor-toto/spor-toto-content.tsx
11. src/components/dashboard/dashboard-content.tsx
12. src/lib/stores/*

15. Son soz

Bu frontend'in degeri yalnizca guzel sayfalar olmasinda degil, backend'deki su domainleri urunlestirmesinde yatar:

• canli ve upcoming mac kesfi
• AI tahminlerinin anlasilir sunumu
• kupon kurma ve kupon saklama deneyimi
• Spor Toto gibi ayri bir oyun modunu desteklemesi
• auth, locale ve dashboard deneyimini tek kabukta toplama

Bir AI bu repo'yu anlayacaksa, bu projeyi "Next.js arayuz" olarak degil "AI destekli spor bahis urununun kullanici deneyim katmani" olarak okumali.