---
title: Phase 0 ADR Set
description: Self-hosted redesign için Faz 0'da kilitlenen mimari kararlar.
status: active
last_updated: 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.