Life OS Belgeleri

Yerel öncelikli, gizlilik odaklı kişisel işletim sistemi. Görevler, alışkanlıklar, finans, hedefler ve daha fazlasını tek bir sakin çalışma alanında toplar.

Bu belge Life OS'u kurmak, kullanmak ve genişletmek için ihtiyacın olan her şeyi içerir. Mimari kararlardan modül davranışına, backend API'sinden Docker dağıtımına kadar.

Hızlı başlangıç

1. Docker — tek komut

En kısa yol. Linux, macOS, Windows ve WSL'de aynı:

bun run docker:start

Bu komut Docker daemon'u kontrol eder, image'i build eder, container'ı arka planda başlatır, healthy olana kadar bekler ve logları takip eder. Bun ya da Node yoksa shell wrapper'larını kullan:

# Linux / macOS / WSL
./start.sh

# Windows PowerShell
.\start.ps1

Açıldıktan sonra http://localhost:3000 adresine git.

2. Tek terminalde geliştirme

Hem Rust backend'i hem de Next.js frontend'i aynı anda başlatır:

bun run dev:all

"Görev oluşturulamıyor" benzeri sorunları engeller — çünkü backend'i unutmak imkansız hâle gelir.

3. Manuel — iki terminal

# Terminal 1 — Rust backend (:8080)
bun run backend:dev

# Terminal 2 — Next.js frontend (:3000)
bun run dev

Yapılandırma

Tüm ortam değişkenleri opsiyoneldir; ekosistem makul varsayılanlarla çalışır.

İki süreç tasarımı

Life OS iki bağımsız süreç olarak çalışır:

1. Rust backend — backend/, axum + sqlx, port :8080. SQLite ile doğrudan ham SQL konuşur, tüm domain modülleri backend/src/*.rs içinde tek dosya.
2. Next.js frontend — src/, port :3000. app/ dizininde sadece layout.tsx, page.tsx ve globals.css var; Next API route'u yoktur.

next.config.ts içindeki rewrites() her /api/* isteğini şeffaf biçimde Rust'a yönlendirir. Bu sayede frontend tek bir fetch() kullanır, geliştirici Rust'ın orada olduğunu fark bile etmez.

Veri akışı

Sayfa bileşeni
  → src/lib/api/hooks.ts (TanStack Query)
  → apiGet/apiPost/apiPatch/apiDelete  (src/lib/api/client.ts)
  → fetch("/api/...")
  → Next.js rewrite → Rust :8080 → SQLite

Her mutasyon başarı sonrası queryClient.invalidateQueries ile UI'yi tazeler. Optimistik güncellemelere şu an dokunulmadı; her şey doğrulanmış sunucu cevabıyla yenilenir.

Veritabanı sözleşmesi

• Aynı dosya — Hem Prisma (migrations) hem Rust (runtime) prisma/dev.db üzerinde çalışır.
• Foreign keys — backend/src/db.rs pool'u foreign_keys(true) ile açar; SQLite varsayılan olarak kapalı tutar ve Prisma'nın cascade delete'leri buna güvenir.
• Önceden oluşturulmuş — create_if_missing(false): Rust binary, DB yoksa hata verir. Önce bun run db:push çalıştır.

Şema değişikliği için Prisma kullanılır:

bun run db:push       # Migrationsız hızlı eşleme
bun run db:generate   # Prisma client'ı yenile
bun run db:seed       # Demo veriyle doldur

Durum yönetimi

• TanStack Query — sunucu verisi için tek doğru kaynak.
• Zustand — yerel UI durumu (seçili modül, filtreler, sidebar, tema, dil, baseCurrency vs.) + persist middleware ile localStorage.

Modüller

Tüm modüller src/components/lifeos/<modül>/ altında tek bir büyük *-page.tsx dosyasında yaşar.

Tasks — composer detayı

Görev oluşturma diyalogu modern bir composer kullanır:

• Borderless büyük başlık girişi, autofocus.
• 4 öncelik pill'i (renkli nokta + accent border).
• Popover chip'leri: tarih (Bugün/Yarın/Bu hafta + manuel), proje, tekrar, etiketler.
• ⌘/Ctrl+Enter ile gönder.
• Boş durum kartındaki "Görev Ekle" butonu artık doğrudan composer'ı açar.

Finance — canlı kurlar

Finans modülü iki katmanlı:

1. Yerel — Hesaplar, işlemler, kategoriler, bütçeler. Tamamen offline.
2. Çevrim içi (opsiyonel) — Avrupa Merkez Bankası referans kurları üzerinden canlı çeviri ve sparkline. Frankfurter ile çalışır (ücretsiz, key gerektirmez).

Kullanıcı Ayarlar → Görünüm → Finans Tercihleri bölümünden tek tıkla canlı kurları kapatabilir. Kapatıldığında dış API'ye hiç istek atılmaz; her hesap kendi para biriminde gösterilir.

Welcome & Setup

İlk açılışta üç adımlı akış:

1. Welcome ekranı — Ayrı, tam-ekran karşılama. Animated logo orb, rotating tagline, üç değer önerisi, "Hadi başlayalım" CTA.
2. Setup Wizard — 8 adım: dil, depolama, görünüm (tema canlı uygulanır), modüller, dashboard widget'ları, hızlı kurulum, özet.
3. App — Dashboard.

welcomeSeen ve setupComplete flag'leri store'da kalıcıdır:

• !setupComplete && !welcomeSeen → Welcome
• !setupComplete → SetupWizard
• diğer → AppShell

Setup sırasında seçilen tema/accent/font anında uygulanır; "Launch" butonu sadece son onaydır. Setup'ı tekrar açmak için: Ayarlar → Tehlikeli Bölge → Kurulum Sihirbazını Sıfırla.

Tema

Üç katman:

• Mod — light / dark / black (OLED) / system. next-themes ile yönetilir.
• Accent — emerald, teal, amber, rose, violet, cyan, indigo, pink, lime, sky veya custom hex. --accent-primary CSS değişkenine yazılır, tüm modüller bunu kullanır.
• Yoğunluk — compact / comfortable / spacious. CSS variable'larla padding/spacing ölçekler.

Logo (public/logo.svg) sidebar, welcome, setup wizard, settings about kartı, README başlığı, GitHub Pages nav ve favicon olarak entegre.

Çoklu dil

5 dil mevcut: en, tr, es, de, fr. Çeviri dosyaları src/lib/i18n/translations/*.ts.

• Tip güvenli: TranslationKeys tipi en'den türetilir; diğer diller bunu satisfy etmeli.
• Eksik anahtarlar için otomatik İngilizce fallback (useTranslation ham anahtar yolu döndürmez).
• Tarayıcı dili welcome ekranı + wizard'da algılanır, kullanıcı override edebilir.

Döviz çevirici detayı

src/lib/finance/currency.ts tek dosyalık modül:

• SUPPORTED_CURRENCIES — USD, EUR, GBP, TRY, JPY, CHF, CAD, AUD, CNY, INR.
• formatCurrency(amount, code) — JPY için 0 ondalık, diğerleri 2.
• useExchangeRates(base, { enabled }) — Frankfurter /latest; 1 saat staleTime, 24 saat gcTime.
• useExchangeRateHistory(from, to, days, { enabled }) — timeseries endpoint; 7g sparkline + 24s delta için.
• convert(amount, from, to, rates) — base üzerinden pivot.

Arama & komut paleti

⌘+K (veya Ctrl+K) komut paleti açar: hızlı modül geçişi, hızlı ekleme aksiyonları. Header'daki arama çubuğu modüller arası içerik araması yapar.

Backend API

Tüm route'lar backend/src/lib.rs içindeki build_app()'te tek noktada kayıtlı. AppState sadece SqlitePool taşır.

Hata yönetimi: backend/src/error.rs içindeki AppError → axum IntoResponse. Tek tip JSON hata gövdesi döndürür.

Uç noktalar

Hepsi /api/ prefix'i ile başlar:

Kimlik doğrulama

API_KEY ortam değişkeni ayarlıysa middleware tüm /api/* isteklerinde Authorization: Bearer <key> başlığını arar. Boşken middleware no-op'tur — yerel geliştirme için güvenli.

CORS varsayılan olarak izin verir. ALLOWED_ORIGIN ayarlanırsa o origin'e kısıtlanır.

Komutlar

Test

Frontend

Vitest + jsdom + Testing Library. src/__tests__/setup.ts Zustand persist için localStorage mock eder. Tek bir dosyayı çalıştırmak için:

bun run test -- src/__tests__/stores/task-store.test.ts

Backend

Rust integration testleri backend/tests/ altında. Her test suite tempfile ile izole bir geçici SQLite kullanır (common::setup_test_app()):

cd backend && cargo test

Docker

Multi-stage Dockerfile: rust-builder → next-builder → runner. Final image node:22-slim tabanlı; Rust binary'si /usr/local/bin/lifeos-backend'e kopyalanır.

• Volume — SQLite verisi life-os-data named volume'unda kalır. docker:reset bu volume'u siler (geri dönüşsüz).
• Entrypoint — docker-entrypoint.sh önce prisma migrate deploy çalıştırır, sonra backend'i background'da başlatır, /health hazır olunca frontend'i başlatır.
• Healthcheck — Hem 3000 hem 8080 sorgulanır. wget runner stage'e eklendi.

Dağıtım

En basit yol Docker:

docker compose up -d --build

Reverse proxy (Caddy / nginx / Traefik) ile HTTPS sonlandırması yapıp, API_KEY ve ALLOWED_ORIGIN ayarlamanız önerilir. Veri SQLite olduğu için snapshot'lar tek dosya kopyalama kadar basit.

Katkıda bulunma

1. Fork & clone.
2. bun install + bun run db:push.
3. Branch: git checkout -b feat/<açıklama>.
4. Geliştir → bun run typecheck + bun run test geç.
5. Commit'leri Conventional Commits formatında yaz.
6. PR aç.

Yeni bir modül eklerken kalıp: src/components/lifeos/<mod>/<mod>-page.tsx + backend/src/<mod>.rs + backend/src/lib.rs route kaydı + src/lib/api/hooks.ts + 5 dil i18n.

SSS

Verilerim nerede tutuluyor?

Sadece senin cihazında. SQLite tek dosya (prisma/dev.db veya Docker'da life-os-data volume'unda). Bulut, hesap, takip yok.

Birden fazla cihazdan kullanabilir miyim?

Şu an gerçek zamanlı sync yok. Manuel yol: Ayarlar → Veri → Dışa Aktar, ardından diğer cihaza içe aktar. Veya container'ı VPS'te tek bir yerde host edip her yerden açabilirsin.

Döviz çeviriciyi tamamen kapatabilir miyim?

Evet. Ayarlar → Görünüm → Finans Tercihleri içinde "Döviz Çeviricisini Etkinleştir" switch'ini kapat. Kapatıldığında Frankfurter API'sine hiç istek atılmaz; uygulama tamamen offline çalışır.

Setup wizard'ı tekrar açabilir miyim?

Ayarlar → Tehlikeli Bölge → Kurulum Sihirbazını Sıfırla. Verilerin korunur.

Hangi tarayıcılar destekleniyor?

Modern evergreen tarayıcılar: Chrome/Edge 110+, Firefox 110+, Safari 16.4+.

Backend Rust olmak zorunda mı?

Hayır, ama tasarım iki süreçli olduğu için frontend Rust'a /api/* üzerinden konuşur. Backend'i değiştirirsen aynı endpoint sözleşmesini koruman gerekir.