Hackathon Monorepo - Yapay Kalem

Bu repo, haber veri işleme, API backend ve interaktif harita bazlı eğitim platformu içeren hackathon projesini barındırır.

hackathon_AA/
├─ apps/                                    # Frontend - Statik site dosyaları
│  ├─ index.html                            # Ana sayfa
│  ├─ search4code.js / .css                 # Ana uygulama mantığı ve stilleri
│  ├─ country-names-tr.js                   # Türkçe ülke isimleri
│  ├─ verilerin_tamami.js                   # Tüm veri seti
│  ├─ assets/badges/                        # Kullanıcı rozetleri (SVG)
│  ├─ data/                                 # Frontend veri dosyaları
│  │  ├─ data.js
│  │  └─ news.js
│  └─ site/                                 # Ek site kaynakları
│
├─ services/api/                            # Backend API (FastAPI)
│  ├─ app/
│  │  └─ main.py                            # API endpoints (auth, articles, xp, leaderboard)
│  ├─ tests/                                # API testleri
│  │  ├─ test_auth.py
│  │  └─ test_articles.py
│  ├─ requirements.txt                      # Python bağımlılıkları
│  └─ .env.example                          # Ortam değişkenleri şablonu
│
├─ data/                                    # Veri depolama
│  ├─ demo.db                               # SQLite veritabanı (kullanıcılar, XP, leaderboard)
│  ├─ raw/                                  # Ham veri dosyaları
│  │  ├─ haber_verileri_ham_hepsi.json      # Tüm ham haberler
│  │  └─ haber_verileri_ham_siniflandirilmis/
│  │     ├─ dunya.json                      # Dünya haberleri
│  │     ├─ ekonomi.json                    # Ekonomi haberleri
│  │     ├─ guncel.json                     # Güncel haberler
│  │     └─ spor.json                       # Spor haberleri
│  ├─ processed/                            # İşlenmiş veriler
│  │  └─ articles/
│  │     └─ articles.json                   # İşlenmiş makale verileri (API tarafından kullanılır)
│  ├─ history_quiz_sorular/                 # Quiz soruları (seviye bazlı)
│  │  ├─ history_quiz_kolay_20.json         # Kolay seviye - 20 soru
│  │  ├─ history_quiz_kolay_30.json         # Kolay seviye - 30 soru
│  │  ├─ history_quiz_orta_20.json          # Orta seviye - 20 soru
│  │  └─ history_quiz_zor_20.json           # Zor seviye - 20 soru
│  ├─ guncel_quiz/                          # Güncel quiz verileri
│  ├─ harita_eklentisi_verileri/            # Harita analiz verileri
│  └─ tts_out/                              # TTS (Text-to-Speech) çıktıları
│     ├─ all/                               # Tüm kategorilerin birleşik MP3 + manifest
│     ├─ dunya/ ekonomi/ guncel/ spor/      # Kategori bazlı TTS çıktıları
│     └─ verbatim_*/                        # Kategori bazlı uzun metinler
│
├─ infra/                                   # Altyapı (Docker Compose)
│  └─ compose.yaml                          # Postgres + Redis servisleri
│
├─ kategori_ekle.py                         # Veri işleme: Kategorileri birleştirme
├─ check_api_countries.py                   # API test: Ülke verilerini kontrol et
├─ find_high_importance_countries.py        # Yüksek önem puanlı haberleri bul
├─ test_api.py                              # API bağlantı testi
├─ sonuclar_kategorili.jsonl                # İşlenmiş kategorili sonuçlar
├─ high_importance_countries.json           # Önem puanı >7.0 olan haberler
│
├─ CONTRIBUTING.md                          # Katkı rehberi (Git flow, kod standartları)
├─ UI_UPGRADES.md                           # UI/UX iyileştirme notları
└─ vercel.json                              # Vercel deployment ayarları

NOT: tts_out/* içeriği TTS çalıştırıldıkça doldurulacak. MP3'ler ve manifestler kategori klasörlerinde, uzun verbatim metinler verbatim* klasörlerinde tutulur.

---

🚀 Hızlı Başlangıç

1) API'yi çalıştır

cd services/api
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export DATA_DIR=../../data
uvicorn app.main:app --reload --port 8000

2) Site'yi aç

apps/index.html dosyasını bir HTTP sunucuyla aç (örn. VSCode Live Server veya Python HTTP server):

# Basit HTTP sunucu ile
cd apps
python -m http.server 5500

Tarayıcınızda: http://localhost:5500

Gerekirse API base URL'ini ayarlayın:

<script>window.API_BASE="http://localhost:8000";</script>

3) JWT ile kimlik doğrulama

# Yeni kullanıcı oluştur
curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"Sifre123","display_name":"Demo"}'

# Giriş yap (aynı kullanıcı)
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"Sifre123"}'

# Kimliği doğrulanmış profili getir
curl http://localhost:8000/auth/me \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

ACCESS_TOKEN değeri register veya login yanıtındaki access_token alanından gelir. Üretimde API_SECRET_KEY ortam değişkenini güçlü bir değere ayarlamayı unutmayın.

4) XP & Leaderboard örneği

TOKEN="<ACCESS_TOKEN>"
curl -X POST http://localhost:8000/xp \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"verb":"quiz_correct","amount":25,"ref_id":"article:123:quiz"}'

# Lider tablosunu görüntüle
curl http://localhost:8000/leaderboard

5) Makale (Articles) API

/articles endpoint'i data/processed/articles/articles.json dosyasından veri döndürür.

Sorgu parametreleri:

• ?limit=N - Maksimum N makale getir
• ?city=... - Belirli bir şehre ait haberleri filtrele
• ?country=... - Belirli bir ülkeye ait haberleri filtrele
• ?importance_score=N - Önem skoru N'den büyük haberleri getir

Örnekler:

# İlk 20 makaleyi getir
curl http://localhost:8000/articles?limit=20

# Türkiye'den haberleri getir
curl http://localhost:8000/articles?country=Türkiye

# İstanbul'dan önem skoru yüksek haberleri getir
curl "http://localhost:8000/articles?city=İstanbul&importance_score=7"

---

👥 Takım ve Görev Dağılımı

• Özgün: Backend API (services/api) - XP sistemi, kullanıcı yönetimi, JWT auth, leaderboard
• Aslı: Veri işleme pipeline'ı, kategori etiketleme, TTS entegrasyonu
• Sema: Harita UI, ülke/şehir filtreleme, veri görselleştirme
• Sümeyye: Frontend UI/UX, glassmorphic tasarım, rozet sistemi, kullanıcı deneyimi

---

🧪 Test Etme

API Testlerini Çalıştırma

cd services/api
pytest tests/ -v

Manuel API Testi

Proje kök dizininde bulunan yardımcı scriptler:

# API bağlantısını test et
python test_api.py

# Yüksek önem puanlı ülkeleri kontrol et
python check_api_countries.py

# Önem puanı >7.0 olan haberleri bul
python find_high_importance_countries.py

---

🐳 Docker Compose (Postgres + Redis) – Opsiyonel

Postgres ve Redis servislerini başlatmak için:

cd infra
docker compose up -d

NOT: Şu an API dosya tabanlı sqlitedict (demo.db) ile çalışmaktadır. Postgres/Redis servisleri gelecekte kullanım için hazır beklemektedir.

---

📊 Veri Yapısı ve İşlem Akışı

1. Ham Veriler (Raw Data)

• Tüm haberler: data/raw/haber_verileri_ham_hepsi.json
• Kategorize edilmiş: data/raw/haber_verileri_ham_siniflandirilmis/*.json

2. Veri İşleme

• kategori_ekle.py: Kategorileri haberlere ekler
• Çıktı: sonuclar_kategorili.jsonl

3. İşlenmiş Veriler (Processed Data)

• API tarafından kullanılan: data/processed/articles/articles.json
• Quiz soruları: data/history_quiz_sorular/*.json

4. Önem Skoru (Importance Score)

Haberler 0-10 arası bir önem skoru ile derecelendirilir:

• 7.0+: Yüksek önem (krizler, önemli gelişmeler)
• 4.0-7.0: Orta önem (güncel haberler)
• <4.0: Düşük önem (genel haberler)

---

📝 Katkı Rehberi

Projeye katkıda bulunmak için:

1. Branching stratejisi:

   • Feature: feat/feature-name
   • Bug fix: fix/bug-name
   • Documentation: docs/doc-name

2. Commit mesajları: Conventional Commits formatı kullanın

   feat(api): add country filter to articles endpoint
   fix(ui): resolve map rendering issue
   docs(readme): update installation steps
   

3. Pull Request:

   • .github/PULL_REQUEST_TEMPLATE.md otomatik olarak yüklenir
   • Değişiklikleri açıkça belirtin
   • Test sonuçlarını ekleyin

Detaylı bilgi için CONTRIBUTING.md dosyasına bakın.

---

🚀 Deployment (Vercel)

Proje Vercel üzerinde deploy edilmeye hazırdır. vercel.json dosyası:

• API isteklerini /api/* path'inden services/api/app/main.py'a yönlendirir
• Statik dosyaları apps/ klasöründen sunar

# Vercel CLI ile deploy
vercel --prod

---

📄 Ek Dökümanlar

• UI/UX İyileştirmeleri: UI_UPGRADES.md - Glassmorphic tasarım, animasyonlar ve kullanıcı deneyimi geliştirmeleri
• Katkı Rehberi: CONTRIBUTING.md - Git flow, kod standartları ve PR süreci
• Uygulanan Düzeltmeler: FIXES_APPLIED.md - Geçmiş bug fix'ler ve iyileştirmeler

---

📜 Lisans

Bu proje hackathon yarışması için geliştirilmiştir. Lisans bilgisi için apps/LICENSE dosyasına bakın.

---

🙏 Teşekkürler

Bu proje Anadolu Ajansı hackathon'u için geliştirilmiştir.