neta/docs/self-hosted-redesign/phase-0-adrs.md

title, description, status, last_updated

title	description	status	last_updated
Phase 0 ADR Set	Self-hosted redesign için Faz 0'da kilitlenen mimari kararlar.	active	2026-07-10

Phase 0 ADR Set

Bu dosya Faz 0 mimari karar kayıtlarını tutar. Kararlar, implementation fazlarında tersine kanıt çıkmadığı sürece geçerlidir. Faz 1 spike'ı bu kararların teknik olarak çalıştığını kanıtlayacak ilk uygulama işidir.

ADR-0001: SQLite + better-sqlite3

Status: Accepted for redesign baseline.

Karar:

• Hedef self-hosted runtime tek instance olacak.
• Veritabanı SQLite olacak.
• Node tarafında synchronous native driver olarak better-sqlite3 kullanılacak.

Gerekçe:

• Freelancer ölçeğinde ayrı Postgres servisi, connection pool ve network latency self-host maliyetini artırıyor.
• Tek persistent volume ile backup/restore daha anlaşılır.
• SQLite WAL ve kısa transaction disiplini bu ürünün beklenen write concurrency ihtiyacına yeterli.

Sınır:

• Horizontal replica yok.
• NFS/shared volume üzerinde aynı DB dosyasını birden fazla app instance yazmayacak.
• Bu sınır aşılırsa PostgreSQL migration ayrı ADR ve faz gerektirir.

ADR-0002: Drizzle ORM ve kaynak kontrollü migration

Status: Accepted for redesign baseline.

Karar:

• Schema ve query katmanı Drizzle ORM ile yazılacak.
• Production'da drizzle-kit push kullanılmayacak.
• Migration dosyaları kaynak kontrolünde, image içinde ve startup migration runner üzerinden uygulanacak.

Gerekçe:

• Type-safe query ihtiyacı var.
• Runtime overhead düşük kalmalı.
• SQLite schema değişimleri deterministic ve review edilebilir olmalı.

ADR-0003: Better Auth

Status: Accepted for redesign baseline.

Karar:

• Supabase Auth yerine Better Auth kullanılacak.
• Email/password ve DB session ilk release için yeterli kapsam.
• İlk freelancer setup akışı public registration yerine kurulum kilidiyle yönetilecek.

Gerekçe:

• Auth protokolünü sıfırdan yazmak gereksiz risk.
• External auth service self-host hedefiyle çelişir.
• Portal client invitation flow Better Auth user/session modeliyle kurulabilir.

ADR-0004: Server-side authorization

Status: Accepted for redesign baseline.

Karar:

• Browser hiçbir zaman DB/auth secret/filesystem import etmeyecek.
• RLS yerine requireSession, role checks ve owner-filtered repository/service functions kullanılacak.
• Authorization testleri her resource için negatif test içerecek.

Gerekçe:

• SQLite RLS sağlamaz.
• Güvenlik sınırı her query/mutation'da server service katmanında kurulmalı.

ADR-0005: Yerel filesystem storage

Status: Accepted for redesign baseline.

Karar:

• Avatar ve project asset dosyaları /app/data/uploads altında saklanacak.
• DB içinde dosya metadata tablosu olacak.
• Upload/download Route Handler'ları auth, owner, size, MIME ve path traversal kontrolü yapacak.

Gerekçe:

• S3 veya Supabase Storage self-host kurulumunu ağırlaştırır.
• Tek volume backup modeli basit kalır.

ADR-0006: Internal Neta UI

Status: Accepted for redesign baseline.

Karar:

• poyraz-ui runtime bağımlılığı kaldırılacak.
• Neta'nın kendi components/ui primitive'leri ve semantic CSS token'ları kullanılacak.
• Dialog, select, menu, tabs gibi davranışlı bileşenlerde tek bir headless primitive katmanı izole edilebilir.

Gerekçe:

• UI bağımlılığı self-host dağıtım ve uzun vadeli bakım riskini artırıyor.
• Ürün UX'i freelancer workflow'una göre yeniden tasarlanacak.

ADR-0007: PWA/offline sync ilk release kapsam dışı

Status: Accepted for redesign baseline.

Karar:

• İlk self-hosted release'te PWA/offline sync hedeflenmez.
• next-pwa kaldırılacak veya devre dışı bırakılacak.

Gerekçe:

• Offline cache, auth/session ve local DB geçişinde ek tutarlılık riski getiriyor.
• Öncelik deploy basitliği ve server-side veri doğruluğu.

ADR-0008: Embeddings operasyonel hedefe taşınmayacak

Status: Accepted for redesign baseline.

Karar:

• document_embeddings pgvector runtime kabiliyeti ilk release'e taşınmayacak.
• Mevcut embeddings archive/import source olarak değerlendirilecek.
• Gerekirse sonraki fazda SQLite FTS5 veya harici vector store için ayrı karar alınacak.

Gerekçe:

• pgvector self-host hedefinde Postgres bağımlılığını geri getirir.
• Mevcut RAG yüzeyi core freelancer workflow'u için kritik değil.

ADR-0009: Para integer minor unit

Status: Accepted for redesign baseline.

Karar:

• Para alanları hedef DB'de integer minor unit olarak saklanacak.
• Formatlama UI/shared formatting katmanında yapılacak.

Gerekçe:

• Decimal farkları, locale parse hataları ve floating point riski azaltılır.
• Aggregate SQL daha net olur.

ADR-0010: journals + daily_logs birleşimi

Status: Accepted for redesign baseline.

Karar:

• Aktif ürün davranışı daily_logs üzerinden devam eder.
• Legacy journals kaynak verisi journal_entries içine merge veya archive edilir.

Gerekçe:

• İki ayrı günlük modeli aynı üründe gereksiz karmaşa yaratıyor.
• Faz 5 journal redesign tek kanonik modeli hedefler.

ADR-0011: Production dual-write yok

Status: Accepted for redesign baseline.

Karar:

• Eski Supabase sürümü redesign tamamlanana kadar production olarak kalacak.
• Yeni sistem ayrı import rehearsal ve maintenance cutover ile devreye alınacak.
• Supabase ve SQLite'a aynı anda production dual-write yapılmayacak.

Gerekçe:

• Dual-write tutarlılık ve rollback riskini artırır.
• Küçük ürün ölçeğinde kontrollü cutover daha güvenli.

ADR-0012: Vercel hedef deploy değil

Status: Accepted for redesign baseline.

Karar:

• Yerel SQLite dosya sistemi gerektiren hedef runtime Vercel serverless/deploy modeline göre tasarlanmaz.
• Hedef Coolify, Dokploy veya standart Docker host'tur.

Gerekçe:

• Persistent local volume ve single long-running Node process gereksinimi var.