MediaTracker

Local-first medya takibi, isteğe bağlı Cloud Sync ve sosyal özellikleri bir araya getiren canlı full-stack web uygulaması.

Canlı uygulama · ArtifactHub vaka çalışması · Mimari ve demo senaryosu · GitHub Actions

TR: Film, dizi, anime, manga, manhwa, manhua ve kitaplarını tek kütüphanede takip et. Kayıt olmadan yerel kullanım; isteğe bağlı hesap, e-posta doğrulaması, cihazlar arası kontrollü eşitleme, ilerleme/hedef/takvim, sosyal etkileşimler ve deterministik öneriler.

EN: A live local-first media tracker for series, films, anime, manga, and books. It supports guest use without an account, optional authenticated Cloud Sync, progress and goal tracking, a calendar, social interactions, and deterministic recommendations.

Production v1 (16 Ekim 2026)

Alan	Mevcut durum
Canlı adres	mediatracker.baglare.com.tr
Uygulama	Next.js 16, React 19, TypeScript, Tailwind CSS 4
Backend	Better Auth, PostgreSQL 18, sunucu tarafı API route'ları ve erişim kontrollü dosya depolaması
Barındırma	TürkHosting / Plesk / Passenger, Node.js 24
Son kabul edilen kaynak	687b944814d1
Canlı doğrulama	Operatör tarafından LIVE/READY, giriş/oturum, Cloud Sync, kayıt/e-posta doğrulaması ve gizlilik sayfası PASS (16 Ekim 2026)

Mühendislik açısından öne çıkanlar

• Local-first: Tarayıcıdaki owner-scoped kütüphane ana kaynaktır. Misafir kullanımı hesap gerektirmez; Cloud bağlantısı olmadan yerel akışlar devam eder.
• Tutarlı eşitleme: Onaylı Cloud upload/download/merge; revision, idempotency, tombstone, tekrar oynatma koruması ve conflict yönetimi.
• Veri bütünlüğü: Sürümlü portable JSON yedekleri, SHA-256 kontrolü, doğrulamalı import ve kontrollü rollback/undo.
• Yetkilendirme: Sunucuda doğrulanan oturumlar, PostgreSQL FORCE RLS, owner izolasyonu, erişim sınırları ve regresyon testleri.
• Ürün özellikleri: Kütüphane, ilerleme, Release Calendar, hedefler, kişiselleştirme, sosyal profil/feed/yorum/bildirimler ve deterministik öneri motoru.
• Yayın disiplini: GitHub Actions doğrulamaları, izole PostgreSQL 18 kabul testleri, SHA sabitli Linux artifact, migration uyumluluğu ve kontrollü rollback prosedürü.

İlk sürümün bilinçli sınırları: Ücretli AI/grounded research sunucu akışları ve yeni TMDB/AniList/OMDb sorguları kapalıdır; Open Library koşulludur. Öneri mantığı aktif sürümde deterministiktir, canlı LLM önerileri olarak sunulmaz. Otomatik gerçek zamanlı Cloud indirmesi yoktur. KVKK veri aktarımı ve bazı operasyonel kapanış maddeleri ayrıca takip edilmektedir; canlı yayın bir genel hukuki uygunluk sertifikası değildir.

Teknik belgeler: Portfolyo kiti · Güncel kapanış/operasyon sınırları · Gizlilik ve sağlayıcı envanteri. Ayrı Supabase adapter'ı ve eski D8 çalışma notları tarihsel/fallback geliştirme bağlamında korunur; Production altyapısı native PostgreSQL'dir.

---

Mevcut Durum

• App Router sayfaları ile sekmeli ana uygulamayı birleştiren Next.js uygulaması.
• Varsayılan kullanım yerel moddur; medya ve ilerleme verisi owner-scoped biçimde tarayıcıda saklanır.
• Native hesap/Cloud yolu Better Auth ve PostgreSQL kullanır; manuel upload/download/merge, owner-scoped sync queue, revision/idempotency ve conflict akışları vardır. Supabase ayrı fallback'tir.
• AI Danışman kütüphane tabanlı deterministik modda kullanılabilir. İlk Production release politikası AI server provider, Grounded Research ve persistent embedding cache yollarını kapalı tutar; API anahtarı eklemek tek başına erişim açmaz.
• Python tabanlı embedding/ML servisi yalnız opsiyonel legacy geliştirme yoludur; Recommendation V2'nin aktif production karar hattı değildir.

Geliştirme aşamaları

Aşama	Durum
D1 — Veri bütünlüğü ve portable backup	Tamamlandı
D2 — Cloud Sync geliştirme ve testleri	Tamamlandı
D2B / D2C Supabase cutover	Tarihsel/fallback geliştirme kayıtları; aktif Production native PostgreSQL 18
D3 — Release Calendar	Tamamlandı
D4 — Product Polish / Performance / UX Reliability	Tamamlandı
D5 — Goals	Yerel ve kontrollü Cloud akışları mevcut; tarihli test kanıtları kendi kapsamlarında
D6 — Recommendation V2	Deterministik karar/fixture ve kayıtlı provider kabul kapsamı tamamlandı
D7 — Grounded Research	Uygulandı; ilk Production release'te kapalı
Production v1	Canlı; native kayıt ve e-posta doğrulaması operatör tarafından kabul edildi
Faz 2	TMDB kapalı tutularak güvenli hazırlık ve repository/CI düzeni

Ayrıntılı sıra ve sonraki aşamalar: docs/ROADMAP.md.

Teknik Kazanımlar

• Offline-first veri mimarisi ve localStorage tabanlı persistence.
• Versioned JSON import/export, kontrollü additive import, checksum, rollback/undo ve portable backup akışı.
• Native Better Auth/PostgreSQL ve ayrı Supabase fallback ile manuel Cloud aktarım, owner-scoped sync queue, V2 revision/idempotency/tombstone ve conflict akışı.
• Local-first kütüphaneden ayrılmış cloud sosyal profil, kullanıcı arama ve takip/engel temeli.
• TVMaze ve contact/User-Agent kapısı sağlanırsa Open Library ile aktif; TMDB v1 live erişimi tüm ortamlarda hard-disabled, AniList v1 live erişimi tüm ortamlarda hard-disabled, OMDb için yalnız legacy kayıt uyumlu normalize medya modeli.
• AI Recommendation V2 için structured provider evidence, deterministik eligibility/ranking ve unresolved hard constraint'lerde optional source-grounded research; LLM final sıralama yapmaz.
• Ana sayfada medya domain durumu, kalıcı kullanıcı tercihleri ve sekme render orkestrasyonu ayrıştırılmış modüler yapı.
• React/Next.js state yönetimi, TypeScript tip güvenliği ve responsive dashboard tasarımı.

Özellikler

• Dashboard, kütüphane, keşfet, takvim, ilerleme, izleme listesi, favoriler, puanlar, notlar, istatistikler, profil, AI Danışman, aktivite ve ayarlar sekmeleri.
• Medya türleri:
  • Film ve dizi
  • Anime
  • Manga, manhwa, manhua
  • Kitap
  • Light novel, web novel, visual novel
• İlerleme takibi:
  • +1, tamamla ve manuel düzenleme akışları
  • Aktivite logları
  • Devam edilen, tamamlanan, duraklatılan, bırakılan ve planlanan içerikler
• Kişisel alanlar:
  • 0-10 kullanıcı puanı
  • Favori işareti
  • Etiketler
  • Kişisel notlar
• Release Calendar:
  • Release policy'nin izin verdiği kaynaklardan 90 günlük otomatik yayın ajandası
  • Aynı normalize olay kümesini kullanan ajanda ve Pazartesi başlangıçlı aylık görünüm
  • Medyaya bağlı kalıcı manuel yayınlar ile stabil provider olaylarını gizleme/geri getirme
  • Aynı D3 veri kümesinden beslenen, sağ panelde ve dar Dashboard görünümünde en fazla üç olayı gösteren “Yakında” özeti
  • Owner-scoped, 12 saat TTL ve stale-while-revalidate otomatik cache; provider cache portable backup veya cloud payload değildir
  • Mimari ve doğrulama ayrıntıları: docs/RELEASE_CALENDAR_ARCHITECTURE.md
• Kütüphane organizasyonu:
  • Dünya filtresi: Doğu, Kadraj, Arşiv
  • Durum, tür, sıralama ve grid/list görünümü
  • TVmaze sezon grupları
  • AniList relation tabanlı güvenli seri gruplama
  • Manuel grup yönetimi
• Keşfet:
  • Global arama paneli
  • Dizi için TVMaze; kitap için geçerli contact/User-Agent yapılandırmasıyla Open Library
  • Film için TMDB live erişimi v1'de hard-disabled; manuel film ve legacy kayıt desteği korunur
  • V1'de live AniList erişimi tüm ortamlarda hard-disabled; legacy kayıtlar desteklenir. Yazılı izin sonrası ayrı post-release source-code enablement ve release gate gerekir.
  • OMDb yeni public arama/fallback zincirinde kapalı; mevcut legacy kayıtlar desteklenir
• Veri yönetimi:
  • Versioned portable JSON yedeği ve SHA-256 bütünlük kontrolü
  • Salt-okunur dosya inceleme ve kullanıcı onaylı additive import
  • Journal, read-back, rollback ve sınırlı undo
  • Duplicate inceleme/birleştirme ve yerel veri bütünlüğü taraması
  • Basit JSON içe/dışa aktarma ve yerel örnek verileri yönetme
  • Format ayrıntıları: docs/PORTABLE_BACKUP_FORMAT.md
• Cloud:
  • Native Better Auth email/password oturumu; ayrı Supabase fallback
  • Production v1'de yeni kayıt açık; oturum için e-posta doğrulaması zorunlu
  • Yerel -> Cloud aktarım
  • Cloud -> Yerel indirme
  • Cloud verisini yerel veriyle birleştirme
  • Mutasyonlar için owner-scoped sync queue, online flush ve reaktif queue → in-flight → ready durum özeti
  • Cloud Media V2 için revision, operation idempotency, tombstone ve kontrollü conflict çözümü
  • Uyuşmayan veya doğrulanamayan rollout sözleşmesinde local kullanımı koruyup Cloud mutation'ı fail-closed durdurma
  • Özel temalar için güvenli JSON import/export ve kullanıcı onaylı, revision kontrollü opsiyonel cloud senkronizasyonu
  • Tema aktarım/senkronizasyon ayrıntıları: docs/THEME_IMPORT_EXPORT_AND_SYNC.md
• Kişiselleştirme:
  • Merkezi preset/custom tema token registry'si; cihaz teması, dünya vurgusu, grafik paleti ve profil sunumunu ayrı modellerde tutma
  • Birbirinden ayrışan Porselen, Tozpembe, Lavanta, Kutup ve Sepya açık tema yüzeyleri
  • Tek SVG mask varlığından üretilen açık/koyu temaya uyumlu logo
  • Dashboard/sağ panel düzeni, yoğunluk, efekt ve başlangıç görünümü tercihleri
  • Erişilebilir collapsible ayarlar ve ayırt edilebilir monokrom grafik paleti
  • Mimari ayrıntılar: docs/PERSONALIZATION_ARCHITECTURE.md
• Sosyal profil:
  • /u/[username] public/protected/personal profil route’u ve /people kullanıcı araması
  • Asimetrik takip/istek, karşılıklı Yin/Yang durumu ve engelleme RPC’leri
  • Kontrollü profil grid’i, avatar/banner ve yalnızca açıkça seçilen vitrin/istatistik/progression/not snapshot’ları
  • Kurulum, görünürlük ve manuel test ayrıntıları: docs/SOCIAL_PROFILE_FOUNDATION.md
  • /feed accepted takiplerden kronolojik aktivite, tek seviye yorum, spoiler ve sınırlı tepki
  • /recommendations yapılandırılmış medya önerisi; cevap/ilerleme yaşam döngüsü ve cihaz bazlı local library link’i
  • /notifications tercihli cloud bildirim merkezi, unread badge ve kontrollü polling
  • Faz 2 veri/RPC/outbox ayrıntıları: docs/SOCIAL_INTERACTIONS_AND_RECOMMENDATIONS.md
• AI Danışman (server provider/research akışları release policy ile kapılı):
  • Kütüphane profiline göre öneri
  • Puanlara, favorilere, ilerlemeye ve notlara göre öneri
  • Dünya kapsamı: karışık, Doğu, Kadraj, Arşiv veya her dünyadan bir öneri
  • Kaynak API'leriyle aday doğrulama
  • Provider fallback akışı
  • Provider, embedding, fallback, aday, kaynak, feedback ve persistent cache durumunu secret göstermeden özetleyen teknik durum alanı
  • Öneri gerekçeleri, kütüphane/devam/keşif bağlamı ve feedback etkisi etiketleri
  • AI oturum geçmişi; sonraki isteğin sıralamasına katılan ilgilenmiyorum geri bildirimi
  • Tekrarlanabilir demo akışları için docs/AI_RECOMMENDATION_DEMO.md

Teknoloji

• Next.js 16.3.8
• React 19.2.4
• TypeScript
• Tailwind CSS 4
• Better Auth, native PostgreSQL 18 ve özel profil dosyası depolaması
• Supabase SSR / Supabase JS (ayrı fallback)
• lucide-react
• FastAPI tabanlı opsiyonel ML servisi
• sentence-transformers tabanlı opsiyonel embedding modeli

Klasör Yapısı

media-tracker/
  app/                    Next.js App Router sayfaları ve API route'ları
  app/api/                TMDB, OMDb, TVmaze, AniList, Open Library ve AI endpoint'leri
  components/             UI bileşenleri
  hooks/                  Client hook'ları
  lib/                    Domain tipleri, storage, sync, AI, Supabase ve API yardımcıları
  lib/ai/                 AI Danışman pipeline'ı, provider'lar ve scoring katmanı
  lib/social/             Sosyal profil domain, doğrulama, görünürlük ve server loader katmanı
  lib/supabase/           Supabase client, repository, mapping ve cloud actions
  ml-service/             Opsiyonel FastAPI embedding servisi
  public/                 Placeholder ve statik görseller
  supabase/schema.sql     Supabase tablo, index, RLS ve cache şeması
  docs/                   Proje içi plan/dokümantasyon
  design_references/      Tasarım referansları; runtime kodu değildir

Hızlı Başlangıç

1. Proje klasörüne gir:

cd media-tracker

2. Bağımlılıkları kur:

npm install

3. Ortam dosyasını hazırla:

copy .env.example .env.local

4. İlk deneme için .env.local dosyasını boş bırakabilirsin. Bu durumda uygulama yerel modda açılır.

5. Geliştirme sunucusunu başlat:

npm run dev

6. Tarayıcıda aç:

http://localhost:3000

Legacy Yerel ML Geliştirme Yolu

Bu bölüm yalnız ayrı yerel geliştirme içindir; Production v1'de AI/ML/research ve kalıcı embedding cache kapalıdır. TMDB içeriği bu servise veya model/cache/dataset yollarına aktarılamaz. Aşağıdaki kurulum normal uygulama kullanımı için gerekli değildir.

1. Python sanal ortamını kur:

cd ml-service
py -3.12 -m venv .venv
.\.venv\Scripts\activate
python -m pip install -r requirements.txt

2. Kök klasöre dön:

cd ..

3. Hazır Windows başlatıcısını çalıştır:

start-dev.bat

Bu betik iki terminal açar:

• ML Service: http://127.0.0.1:8001
• Next.js Web: npm run dev

ML servis sağlık kontrolü:

http://127.0.0.1:8001/health

Ortam Değişkenleri

Temel yerel kullanım için hiçbir değişken zorunlu değildir. Provider anahtarları tek başına yetki veya release gate açmaz. İlk Production release sözleşmesi AI_SERVER_ACCESS_MODE=disabled, research kapalı ve persistent embedding cache off değerlerini gerektirir; ayrıntılar güncel release/env authority ve gate matrisi içindedir.

Değişken	Zorunlu mu?	Kullanım
NEXT_PUBLIC_SUPABASE_URL	Hayır	Opsiyonel Supabase auth ve kontrollü Cloud aktarımı için
NEXT_PUBLIC_SUPABASE_ANON_KEY	Hayır	Supabase client bağlantısı için
NEXT_PUBLIC_CLOUD_MEDIA_SCHEMA_STAGE	Hayır	Cloud şema fazı: local varsayılan legacy; D2B.1 ortamı için kontrollü d2b1
NEXT_PUBLIC_CLOUD_MEDIA_V2_ENABLED	Hayır	Cloud Media V2 adapter'ını açıkça etkinleştirir; varsayılan false
NEXT_PUBLIC_CLOUD_MEDIA_MAINTENANCE	Hayır	Bakım sırasında Cloud mutation dispatch'ini durdurur
NEXT_PUBLIC_CLOUD_MEDIA_DEPLOYMENT_EPOCH	Hayır	Açık istemcilerde deployment değişimini ve kontrollü reload gereksinimini tanımlar
NEXT_PUBLIC_CLOUD_MEDIA_MINIMUM_CLIENT_VERSION	Hayır	Minimum uyumlu istemci sözleşmesini tanımlar
SUPABASE_SERVICE_ROLE_KEY	Hayır	İlk release normal web runtime için gerekmez; ops/script ve ayrı gated geliştirme yolları içindir
OMDB_API_KEY	Hayır	Yalnız legacy/local teşhis; public search/fallback açmaz
AI_SERVER_ACCESS_MODE	Hayır	Eksik/geçersiz değer disabled; ilk Production release'te disabled
MEDIA_TRACKER_PROVIDER_USER_AGENT	Open Library için	Gerçek contact içeren MediaTracker User-Agent; eksikse provider kapalı
AI_PROVIDER	Production v1 yasak; yalnız ayrı local geliştirme	mock, auto, openai, gemini, openrouter, groq
OPENAI_API_KEY	Production v1 yasak; yalnız ayrı local geliştirme	OpenAI uyumlu provider
OPENAI_MODEL	Production v1 yasak; yalnız ayrı local geliştirme	Varsayılan: gpt-5.4-mini
GEMINI_API_KEY	Production v1 yasak; yalnız ayrı local geliştirme	Gemini provider
GEMINI_MODEL	Production v1 yasak; yalnız ayrı local geliştirme	Varsayılan: gemini-2.0-flash
OPENROUTER_API_KEY	Production v1 yasak; yalnız ayrı local geliştirme	OpenRouter provider
OPENROUTER_MODEL	Production v1 yasak; yalnız ayrı local geliştirme	Varsayılan: openrouter/free
GROQ_API_KEY	Production v1 yasak; yalnız ayrı local geliştirme	Groq provider
GROQ_MODEL	Production v1 yasak; yalnız ayrı local geliştirme	Varsayılan: llama-3.1-8b-instant
NEXT_PUBLIC_APP_URL	Hayır	OpenRouter header bilgisi için
MEDIA_TRACKER_ML_SERVICE_URL	Production v1 yasak; yalnız ayrı local geliştirme	Python embedding servisi URL'si. Örnek: http://127.0.0.1:8001
MEDIA_TRACKER_EMBEDDING_MODEL	Production v1 yasak; yalnız ayrı local geliştirme	Varsayılan: sentence-transformers/all-MiniLM-L6-v2
MEDIA_TRACKER_EMBEDDING_CACHE	Hayır	off verilirse embedding cache kapanır
MEDIA_TRACKER_PERSISTENT_EMBEDDING_CACHE	Hayır	off verilirse Supabase tabanlı embedding cache kapanır

Güvenlik notu: Production v1 normal web runtime içinde service-role ve paid AI anahtarları yasaktır. Persistent embedding cache kapalıdır. Ayrı yetkili operasyonlarda kullanılan secret hiçbir client component, API yanıtı veya loga eklenmemeli ve NEXT_PUBLIC_ prefix'i almamalıdır. .env.local ve gerçek anahtarlar Git'e gönderilmemelidir.

Native Hesap/Cloud ve Ayrı Supabase Fallback

Production v1 hesabı Better Auth, PostgreSQL 18 ve native özel dosya depolamasını kullanır. E-posta doğrulaması tamamlandıktan sonra giriş yapılır. Plesk/Passenger, PostgreSQL veya SMTP kurulumu bu README üzerinden değiştirilmez. Native mimari için backend temeli ve e-posta akışı incelenebilir; bu belgelerin tarihli kabul statüleri güncel canlı teyitle karıştırılmamalıdır.

Aşağıdaki Supabase adımları yalnız ayrı fallback geliştirme ortamı içindir; aktif native Production kurulumu veya hesap taşıma yönergesi değildir:

1. Supabase projesi oluştur.
2. Yeni yerel/disposable kurulumda repository migration zincirini kendi izole ortamında doğrula. Eski D2B/D2C ledger ifadeleri tarihsel kanıttır; güncel hosted durum LIVE_UNVERIFIED. Production işlemleri README kapsamı değildir; güncel authority 06D release operations ve 06E release gates içindedir. D8 dokümanları yalnız tarihsel kanıttır.
3. Supabase Project Settings -> API bölümünden URL ve anon key değerlerini al.
4. .env.local içine şunları ekle:

NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...

5. Uygulamayı yeniden başlat.
6. Ayrı fallback ortamının yetkili hesabıyla giriş ve Cloud veri durumunu kontrol et. Bu ortamın signup politikası native Production kaydından bağımsızdır.

Cloud davranışı:

• Guest/local-first kullanım hesap gerektirmez.
• Hesap/Cloud adapter'ı backend seçimine bağlıdır; Supabase değişkenlerinin olmaması native hesabı kapatmaz.
• Yerel veri yine arayüzün ana kaynağıdır.
• Cloud upload, download ve merge işlemleri kullanıcı onayıyla yapılır.
• Giriş yapılmış ve online durumdaysan yerel mutasyonlar sync queue üzerinden cloud'a gönderilir; ağ veya oturum yoksa bekleyen işlemler kuyrukta kalır.
• Sync kartı pending, canlı in-flight, retryable/blocked, adapter/rollout ve son sonuç durumlarını aynı reaktif snapshot'tan gösterir.
• Rollout sözleşmesi bakım, sürüm veya bilinmeyen şema nedeniyle hazır değilse Cloud mutation gönderimi durur; yerel veri ve yerel kullanım etkilenmez.
• Cloud'dan otomatik real-time pull yoktur; indirme ve birleştirme manuel aksiyonlarla yapılır.

Fallback D2B.1 geliştirme örneği .env.example içindedir. Ortamlar ve hesap verileri otomatik taşınmaz.

Veri Saklama

Tarayıcıda kullanılan önemli localStorage anahtarları:

• media-tracker-list: medya listesi
• media-tracker-logs: ilerleme logları
• mediaTracker:uiPreferences: filtre ve görünüm tercihleri
• mediaTracker:profilePreferences: profil tercihleri
• media-tracker-right-rail-preferences: sağ panel tercihleri
• media-tracker-sync-queue: sync kuyruğu
• media-tracker-ai-settings: AI Danışman ayarları
• media-tracker-ai-sessions: AI oturum geçmişi
• media-tracker-ai-active-session: aktif AI oturumu
• media-tracker-ai-recommendation-feedback: AI öneri geri bildirimleri

Kullanılabilir Komutlar

npm run dev

Geliştirme sunucusunu başlatır.

npm run build

Production build alır.

npm run start

Build sonrası production sunucusunu başlatır.

npm run lint

ESLint kontrollerini çalıştırır.

npm run test
npm run test:run

Vitest'i izleme modunda veya tek seferlik test paketi olarak çalıştırır.

API Route'ları

• POST /api/tmdb/search — JSON { "query": "...", "mediaType": "movie" }; mediaType ayrıca tv olabilir
• GET /api/tmdb/details?id=...
• GET /api/omdb/search?q=...
• GET /api/omdb/details?id=...
• POST /api/tvmaze/search ({ "query": "..." })
• GET /api/tvmaze/details?id=...
• POST /api/anilist/search (query + bounded category)
• GET /api/anilist/details?id=...&type=...
• POST /api/openlibrary/search ({ "query": "..." })
• GET /api/calendar/tvmaze?showId=...&season=...
• GET /api/calendar/anilist?mediaId=...
• GET /api/calendar/tmdb?movieId=...
• POST /api/ai/recommend

Dış API anahtarları server-side route'larda kullanılır; tarayıcıya token gönderilmez. Release Calendar route'ları yalnız yapılandırılmış provider kimliklerini kabul eder; başlık eşleştirmesi yapmaz ve sonuçları önümüzdeki 90 günle sınırlar. TMDB release takvimi yalnız merkezi release policy ilgili kaynağı etkinleştirirse çağrılır; provider erişilemezse geçerli stale cache gösterilmeye devam eder.

Release Calendar yerel-first çalışır. Otomatik provider olayları yeniden üretilebilir cache'tir; manuel olaylar ve gizleme kararları ilgili MediaItem metadata'sında kalıcı kullanıcı verisi olarak saklanır. Push bildirimi, harici takvim export'u bu sürümün kapsamında değildir. Manuel olaylar provider ufkundan bağımsız olarak geçmiş ve gelecek aylarda görüntülenebilir.

Opsiyonel ML Servisi

ml-service/ FastAPI tabanlı küçük bir embedding servisidir.

Endpoint'ler:

• GET /health: servis durumunu döner.
• POST /embed: verilen input listesinden embedding vector üretir.

Next.js tarafı MEDIA_TRACKER_ML_SERVICE_URL doluysa bu servisi kullanır. Servis kapalıysa veya hata verirse uygulama local mock embedding fallback'i ile devam eder.

Geliştirme Notları

• Next.js 16 ve React 19 kullanıldığı için render-phase state update kurallarına dikkat edilmelidir.
• localStorage hidrasyonu mount effect'lerinde yapılır.
• Mutasyon akışlarında state güncellemesi ve sync queue yan etkileri ayrı tutulmalıdır.
• app/page.tsx composition root olarak kalır; medya mutasyonları hook'ta, kalıcı tercihler ayrı hook'ta ve ortak sekme blokları orchestration component'inde tutulur.
• Yeni medya kaynağı eklenirse normalizer, global search, AI candidate source union'ları ve UI label'ları birlikte güncellenmelidir.
• AniList otomatik gruplama title benzerliğiyle yapılmaz; güvenli relation verisi kullanılır.
• Bilinmeyen total progress için sahte 1 fallback'i yerine kaynağın semantiğine uygun değer korunmalıdır.

Mimari Belgeler

• Frontend mimarisi
• Yerel veri formatı ve recovery
• Yerel veri bütünlüğü scanner/repair
• Portable Backup V2
• Cloud Media V2 planı
• Cloud migration/cutover runbook
• Release Calendar mimarisi
• Kişiselleştirme mimarisi
• D4 genel bakış ve kabul
• Roadmap

Bilinen Sınırlamalar

• Production v1 canlıdır; bu çalışma ağacındaki Faz 2 değişiklikleri ayrıca yayınlanana kadar canlı sürümün parçası değildir.
• Cloud'dan otomatik realtime pull yoktur; download/merge kullanıcı aksiyonudur.
• Release Calendar otomatik provider ufku 90 gündür. Push/e-posta, ICS/Google Calendar ve streaming availability zorunlu kapsamda değildir.
• TMDB v1 live erişimi env/token değerlerinden bağımsız hard-disabled; AniList v1 live erişimi env'den bağımsız tüm ortamlarda hard-disabled kalır; provider erişilemezse diğer kaynaklar ve geçerli stale Release Calendar cache'i korunur.
• Contract/unit testleri canlı Supabase, RLS veya production deployment kanıtı değildir.

Roadmap Özeti

D1–D7 implementation ve kayıtlı kabul kapsamı mevcut; D6 deterministik final sıralama, D7 ise explicit gate ile çalışan source-grounded research altyapısıdır. İlk Production release'te library-only deterministik öneri açık kalabilir; server AI/research ve persistent embedding cache kapalı tutulur. LLM final sıralama yapmaz.

Native Production v1 canlıdır. D8/Supabase cutover ve kabul tabloları tarihsel kanıt olarak korunur. Güncel aşama özeti roadmap, TMDB izin/saklama sınırları Faz 2 hazırlık sözleşmesi içindedir. Production'da TMDB, ücretli AI/research ve kalıcı embedding cache kapalı kalır. CI, main ve release/v1-hardening push'larında validation → disposable PG18 proof → native Linux artifact zincirini çalıştırır; deployment yapmaz.

Sorun Giderme

Uygulama yerel modda açılıyor

Guest kullanımında bu normaldir. Native hesap için native backend yapılandırması gerekir; yalnız Supabase değişkenlerini eklemek native hesabı yapılandırmaz.

Film araması sonuç vermiyor

TMDB live erişimi v1'de LOCAL/DEVELOPMENT/CI/PREVIEW/PRODUCTION için source-level hard-disabled. Env/token/logo tek başına erişim açamaz; future enablement ayrı legal/provider, retention, AI isolation, attribution/branding review, source-code değişikliği ve release acceptance gerektirir. OMDb yeni arama fallback'i değildir.

AI Danışman gerçek provider kullanmıyor

İlk Production release'te AI_SERVER_ACCESS_MODE=disabled zorunludur; gerçek provider kontrolleri kapalı kalır ve deterministik kütüphane modu çalışır. Provider enablement ayrı post-release güvenlik/bütçe kapısıdır.

Embedding provider local_mock görünüyor

Bu, Python ML servisi kullanılmadığında beklenen davranıştır. Gerçek embedding için ML servisini başlat ve MEDIA_TRACKER_ML_SERVICE_URL değerini ayarla.

Supabase giriş var ama cloud sayıları gelmiyor

supabase/schema.sql çalıştırılmamış olabilir veya RLS/policy ayarları eksik olabilir. Supabase URL ve anon key değerlerini de kontrol et.

Kullanım Akışı

1. Uygulamayı aç.
2. Keşfet sekmesinden içerik ara veya manuel medya ekle.
3. Kütüphanem sekmesinde filtrele, sırala ve grupları düzenle.
4. Medya kartlarından ilerleme, puan, favori ve not bilgilerini güncelle.
5. Aktivite ve istatistik sekmelerinden ilerlemeni takip et.
6. İstersen Ayarlar sekmesinden JSON yedeği al.
7. Supabase yapılandırdıysan cloud aktarım veya birleştirme işlemlerini onayla.
8. AI Danışman sekmesinden kütüphanene göre öneri al.