TechEventRadar

Türkiye'nin teknoloji etkinlik radarı — bootcamp, hackathon, seminer ve kariyer etkinliklerini tek ekranda topla.

English README

Tek cümle amaç: Öğrencilerin ve yeni mezunların güncel teknoloji etkinliklerini tek yerde kolayca bulması.

TechEventRadar; bootcamp, webinar, hackathon, kariyer etkinliği ve topluluk buluşmalarını farklı kaynaklardan toplayıp tek bir ekranda sunar. Böylece öğrenciler "hangi etkinlik ne zaman, nerede, nasıl başvurulur" sorularını tek tek siteleri gezmeden yanıtlayabilir.

İçindekiler

• Neden Bu Proje?
• Öne Çıkan Özellikler
• Mimari
• Hızlı Başlangıç (Docker)
• Scrapers
• API Docs
• Geliştirme (Local)
• Katkı Sağlama
• Yol Haritası
• Destek / Sponsorship

Neden Bu Proje?

Öğrenciler için en büyük problem bilgiden çok dağınıklık:

• Etkinlikler farklı platformlara dağılmış durumda
• Son başvuru tarihleri kolayca kaçırılıyor
• Ücretsiz/online etkinlikleri filtrelemek zaman alıyor

TechEventRadar bu dağınıklığı azaltmak için geliştirildi.

Öne Çıkan Özellikler

🔎 Tek listede arama & filtreleme	Kaynak, konum, tarih aralığı, ücretsiz/geçmiş etkinlik filtreleri
🏷️ Kategori tag sistemi	Hackathon, Seminer/Webinar, Atölye, Konferans, Bootcamp badge'leriyle filtreleme
📡 10 kaynaktan otomatik toplama	Günlük scraper döngüsüyle güncel kalır
🔔 Çok kanallı bildirimler	E-posta, tarayıcı push ve Telegram kanalı
🗓️ Takvim & RSS	.ics takvime ekleme, RSS feed, PWA desteği
🛠️ Admin paneli	İçerik, duyuru ve öneri/şikayet yönetimi

🌐 Canlı Demo: eventradar.dev

Mimari

┌─────────────────────────────────────────────────────────┐
│                  Frontend (React + Vite)                 │
│                    http://localhost:3000                  │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                 Backend (FastAPI)                        │
│                  http://localhost:8000                   │
│   /api/events  /api/sources  /api/admin  /health  /docs  │
└──────────┬─────────────────────────────┬────────────────┘
           │                             │
  ┌────────▼────────┐          ┌─────────▼─────────┐
  │   PostgreSQL    │          │     Scrapers       │
  │  (Events DB)    │          │  youthall, akbank  │
  └─────────────────┘          │  techcareer, ...   │
                               └────────────────────┘

• Backend: FastAPI + SQLAlchemy + PostgreSQL
• Frontend: React (Vite)
• Scraping: Python tabanlı scraper modülleri (Selenium + requests)
• Deployment: Docker Compose

Etkinlik Veri Akışı

Source Catalog
      │
      ▼
Scrape Run Coordinator ── retry / çalışma metrikleri / hata alarmı
      │
      ▼
Event Ingestion ── tarih ve konum normalizasyonu / tag / transaction
      │
      ├── Source Reconciliation ── kaynaktan kaldırılan kayıtları pasifleştirir
      └── Telegram ── commit sonrası yeni etkinlik bildirimi

• app/services/source_catalog.py: On kaynağın canonical kayıtları ve lazy runner adapter'ları
• app/services/scrape_run.py: Fetch, retry, ingestion, reconciliation ve tek çalışma logu
• app/services/event_ingestion.py: Canonical etkinlik yazımı ve yaşam döngüsü kuralları
• app/services/source_quality.py: Kaynak başarı oranı ve veri tamlığı metrikleri
• CONTEXT.md ve docs/adr/: Domain dili ve kabul edilmiş mimari kararlar

Hızlı Başlangıç (Docker)

git clone https://github.com/Metrohan/eventradar.dev.git
cd eventradar.dev
cp .env.example .env
# .env içinde SECRET_KEY, ADMIN_USERNAME, ADMIN_PASSWORD değerlerini düzenle
docker compose up -d --build
docker compose exec backend alembic upgrade head
sleep 10
curl http://localhost:8000/health
# Frontend: http://localhost:3000

Scrapers

Kaynak	Durum	Çalışma biçimi
TechCareer	✅ Aktif	Tarayıcı (Selenium)
Youthall	✅ Aktif	Tarayıcı (Selenium)
Akbank Gençlik	✅ Aktif	Tarayıcı (UC)
Pupilica	✅ Aktif	Tarayıcı (UC)
Kodluyoruz	✅ Aktif	HTTP
Anbean	✅ Aktif	HTTP
Coderspace	✅ Aktif	Tarayıcı (UC)
Tech Istanbul	✅ Aktif	HTTP API
Patika.dev / Skillcamp	✅ Aktif	HTTP
Komünite	✅ Aktif	HTTP

API Docs

• Swagger UI: http://localhost:8000/docs
• Health check: http://localhost:8000/health
• Etkinlikler: GET /api/events?page=1&page_size=20&active_only=true
• Kaynak kataloğu: GET /api/sources

Troubleshooting

Port 8000 zaten kullanımda:

lsof -i :8000
kill -9 <PID>

Database connection error: .env içindeki DATABASE_URL değerinin docker-compose.yml'deki servis adıyla eşleştiğini kontrol et.

Scraper Chrome hatası: Scraper logları için: GET /api/admin/scrapers/logs (admin token gerekli)

Geliştirme (Local)

Backend

pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend

cd frontend
npm ci
npm run dev

Testler

pip install -r requirements-dev.txt
pytest -m "not integration"          # Unit testler
pytest -m integration                # Gerçek scraper testleri (Chrome gerekli)

Katkı Sağlama

Katkıların proje için çok değerli. Küçük düzeltmeler bile büyük etki oluşturur.

Nasıl katkı verebilirsin?

• Yeni scraper kaynağı eklemek
• Mevcut scraper hatalarını düzeltmek
• Tarih/konum ayrıştırma doğruluğunu artırmak
• Frontend filtreleme ve UX iyileştirmeleri
• Dokümantasyon ve test kapsamını geliştirmek

İlk Katkını Seç

good first issue etiketli, kolay başlangıç için hazırlanmış açık işler:

• #46 Event detail page retries 404 responses unnecessarily
• #42 Login error message hardcoded in English while rest of app is Turkish
• #37 Expand AnalyticsService test coverage for get_stats edge cases
• #36 Fix redundant alt text on GitHub icon in Header
• #34 Add aria-label to theme toggle button

Daha fazlası için: tüm good first issue etiketli işler

Adım adım katkı akışı

1. Bu repoyu fork et
2. Yeni bir branch aç
3. Değişikliğini yap
4. Test et
5. Açıklayıcı bir Pull Request gönder

Örnek:

git checkout -b feat/add-new-source
git add .
git commit -m "feat: add new event source scraper"
git push origin feat/add-new-source

Daha detaylı rehber için: CONTRIBUTING.md

Güvenlik ve Gizlilik

Bu proje açık kaynak sürümde secret/credential içermez. Şüpheli bir güvenlik problemi görürsen lütfen SECURITY.md üzerinden bildir.

Yol Haritası

Uzun vadeli hedef: TechEventRadar'ı yalnızca Türkiye'ye değil, dünyanın her ülkesinden teknoloji etkinliklerini çekebilen, geliştiricilerin küresel fırsatları tek yerden keşfedebildiği bir platforma dönüştürmek.

Faz 1 — Temel ✅ (Tamamlandı)

• Çoklu kaynaklardan otomatik etkinlik toplama (10 kaynak)
• Kategori tag sistemi (Hackathon, Bootcamp, Seminer…)
• Admin paneli ve içerik yönetimi
• Telegram bildirim sistemi
• CI/CD pipeline ve test altyapısı

Faz 2 — Kalite & Güvenilirlik 🔧 (Devam ediyor)

• Yeni Türkçe kaynaklar: Skillcamp/Patika, Komünite
• Scraper'lara retry mekanizması ve hata yönetimi
• Kaynak bazlı kalite metrikleri (başarı oranı, veri tamlığı)
• Konum verisi normalizasyonu (Online / şehir bazlı)
• Geçmiş etkinliklerin otomatik arşivlenmesi

Faz 3 — Ürün Büyümesi 🚀 (Yakın dönem)

• Tarayıcıda saklanan favoriler ve filtre tercihleri (hesapsız)
• E-posta / tarayıcı bildirim abonelikleri
• RSS feed aboneliği
• Gelişmiş arama ve filtreleme (şehir, tarih aralığı, ücret)
• Etkinlik takvimi görünümü
• Mobil uyumlu PWA

Faz 4 — Uluslararasılaşma 🌍 (Uzun dönem)

• Çok dilli arayüz (TR / EN)
• Ülke ve bölge bazlı filtreleme
• Uluslararası kaynak entegrasyonları (Eventbrite, Luma, Devpost…)
• Herhangi bir ülkenin tech etkinliklerini çekebilen adaptör mimarisi
• Global etkinlik haritası

Lisans

MIT Lisansı: LICENSE

---

Bu proje öğrencilerin fırsatlara daha hızlı ulaşabilmesi için geliştiriliyor. İyi bir etkinlik bazen kariyerin yönünü değiştirir.

Scraper'ı Manuel Çalıştırma

Etkinlikleri anlık çekmek için:

docker compose run --rm scraper python scripts/run_daily_scrape.py

E-posta ve Tarayıcı Bildirimleri

E-posta aboneliği double opt-in ile çalışır: kullanıcı onay bağlantısını açtıktan sonra haftalık özete dahil edilir.

Önerilen: Resend (kendi domain'inden gönderim). eventradar.dev'i resend.com üzerinde doğrulayıp (SPF/DKIM/DMARC kayıtları) API key aldıktan sonra:

SMTP_HOST=smtp.resend.com
SMTP_PORT=587
SMTP_USER=resend
SMTP_PASS=<Resend API key>
SMTP_FROM=TechEventRadar <noreply@eventradar.dev>

Alternatif: Gmail SMTP (domain doğrulaması yapmak istemiyorsan, normal hesap şifresi yerine Google Uygulama Şifresi kullan — bu durumda SMTP_FROM mutlaka kimlik doğrulanan Gmail adresiyle aynı olmalı, aksi halde SPF/DKIM eşleşmez ve mailler spam'e düşer):

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=hesabin@gmail.com
SMTP_PASS=<16-karakterlik-uygulama-sifresi>
SMTP_FROM=hesabin@gmail.com

Tarayıcı bildirimleri için VAPID anahtarlarını üretip .env dosyasına ekle:

python scripts/generate_vapid_keys.py

VAPID_PRIVATE_KEY=<private-key>
VAPID_PUBLIC_KEY=<public-key>

Ardından servisleri yeniden oluştur ve public key'i doğrula:

docker compose up -d --force-recreate backend scraper
curl http://localhost:8000/api/push/vapid-public-key

Yanıttaki key boş olmamalı. Haftalık e-posta özeti için sunucu cron örneği:

0 9 * * 1 cd /path/to/eventradar.dev && docker compose exec -T backend python scripts/send_weekly_email_digest.py >> /var/log/eventradar-email-digest.log 2>&1

Secret değerlerini repoya veya .env.example dosyasına yazma.

Scraper Hata Alarmı (Telegram)

Scraper coordinator, aynı kaynak art arda üç kez başarısız olduğunda uygulama içinden Telegram alarmı gönderir:

TELEGRAM_BOT_TOKEN=<BOT_TOKEN>
TELEGRAM_CHANNEL_ID=<CHANNEL_ID>

Log dosyalarında geçen diğer kritik hataları ayrıca izlemek istersen isteğe bağlı log monitörünü çalıştırabilirsin:

export TELEGRAM_BOT_TOKEN="<BOT_TOKEN>"
export TELEGRAM_CHAT_ID="<CHAT_ID>"
python3 scripts/monitor_alerts.py

Sürekli izleme için cron örneği (her 2 dakikada bir):

*/2 * * * * cd /path/to/eventradar.dev && TELEGRAM_BOT_TOKEN=<BOT_TOKEN> TELEGRAM_CHAT_ID=<CHAT_ID> /usr/bin/python3 scripts/monitor_alerts.py >> /var/log/eventradar-alerts.log 2>&1

---

Destek / Sponsorship

TechEventRadar tamamen ücretsiz ve açık kaynak. Domain ve sunucu maliyetlerini karşılamak için desteğine ihtiyacımız var.

Bu projeyi faydalı buluyorsan, bir kahve ısmarlayarak sürdürülebilirliğine katkıda bulunabilirsin.

Nereye gidiyor?

• eventradar.dev domain yenileme (~1.000 TL/yıl)
• Sunucu barındırma maliyetleri

---

Katkıda Bulunanlar

Projeye katkıda bulunan herkese teşekkürler! Bu liste her main push'unda contributors-readme-action tarafından otomatik güncellenir.

Metrohan

4ykutG

onurege3467

aqilaziz

Blut-agent

rashmitha-j