diff --git a/ROADMAP.md b/ROADMAP.md deleted file mode 100644 index 6a40b3f..0000000 --- a/ROADMAP.md +++ /dev/null @@ -1,884 +0,0 @@ -# Freelancer OS Roadmap - -Bu dokuman, uygulamanin temel urun yonunu ve MVP kapsamını tanımlar. - -Uygulamanin cikis noktasi: Freelancer'larin gundelik hayatlarini, musterilerini, projelerini, side project'lerini, finansal durumlarini ve kisisel performanslarini tek bir self-host edilebilir dashboard uzerinden yonetebilmesi. - -MVP, tek kullanici odakli olacak. Ekip, ajans, CRM otomasyonlari, gelismis AI modulleri ve mobil uygulama MVP sonrasi fazlara birakilir. - ---- - -## Urun Vizyonu - -Freelancer icin tek merkezli bir operasyon paneli: - -- Bugun ne yapacagim? -- Hangi musteride hangi is var? -- Hangi proje gecikiyor? -- Side project'lerimde ilerleme var mi? -- Bu ay ne kadar kazandim, ne kadar harcadim? -- Enerjim ve ruh halim is performansimi nasil etkiliyor? -- Tum bu verilerden hangi raporu okuyabilirim? - -Uygulama, klasik gorev takip aracindan daha genis; freelancer'in is, finans ve kisisel performans alanlarini birlestiren bir "Freelancer OS" olarak konumlanir. - ---- - -## MVP Ilkeleri - -1. **Tek kullanici** - - MVP'de ekip, rol, yetki, assignee, ortak calisma yok. - - Tum veriler tek kullanicinin kendi calisma alani icindir. - -2. **Self-host ve open-source uyumlu** - - Kurulum dokumani net olmali. - - Veritabani migration'lari repo icinde olmali. - - Harici servisler opsiyonel olmali. - -3. **Gercek veri, sade akis** - - Mock dashboard yerine kullanicinin girdigi gercek verilerden rapor uretilecek. - - Her modulde minimum CRUD ve minimum rapor yeterli. - -4. **AI destekleyici, cekirdek degil** - - MVP'de AI sadece genel chatbot olarak konumlanir. - - Chatbot, kayitli gorev/proje/musteri/finans/gunluk verileri hakkinda soru cevap yapabilir. - - Modul icindeki otomatik oneriler, scoring, akilli otomasyonlar MVP sonrasi. - -5. **Ekranda rapor yeterli** - - MVP'de PDF/PNG export sart degil. - - Dashboard ve modul rapor ekranlari yeterli kabul edilir. - ---- - -## MVP Kapsami - -### 1. Dashboard - -**Amac:** Freelancer'in gunluk ve haftalik durumunu tek bakista gostermek. - -MVP icerigi: - -- Bugunku gorevler -- Yaklasan takvim etkinlikleri -- Aktif musterilerden acik isler -- Aktif projeler ve side project'ler -- Bu ay gelir/gider ozeti -- Haftalik gorev tamamlama grafigi -- Mood/energy trend grafigi -- Geciken isler ve yaklasan deadline'lar - -Raporlar: - -- Haftalik is yuklemesi -- Proje ilerleme ozeti -- Aylik finans ozeti -- Kisisel enerji/mood ozeti - ---- - -### 2. Musteriler - -**Amac:** Freelancer'in calistigi musterileri ve o musterilerle iliskili isleri takip etmesi. - -MVP alanlari: - -- Musteri adi -- Firma/marka adi -- E-posta -- Telefon veya iletisim notu -- Durum: active, paused, archived -- Notlar - -MVP aksiyonlari: - -- Musteri ekleme -- Musteri duzenleme -- Musteri arsivleme -- Musteriye bagli projeleri/gorevleri gorme - -Raporlar: - -- Aktif musteri sayisi -- Musteri bazli proje sayisi -- Musteri bazli gelir ozeti - -MVP disi: - -- Gelismis CRM pipeline -- E-posta entegrasyonu -- Otomatik takip hatirlatmalari -- Musteri sentiment analizi - ---- - -### 3. Projeler ve Side Project'ler - -**Amaç:** Müşteri projeleri ve kişisel side project'leri aynı temel mantıkla ama ayrı türlerle takip etmek. Proje yönetimi yalnızca görevlerden oluşmaz; proje hedefi, çözdüğü problem, kapsamı, görsel kimliği ve planlama notları da projenin ana parçasıdır. - -MVP alanları: - -- Proje adı -- Tür: client_project, side_project -- Bağlı müşteri, sadece client_project için opsiyonel/zorunlu -- Kapak görseli, kullanıcının bilgisayarından yüklenir -- Kapak görseli alt metni -- Açıklama -- Durum: planning, active, paused, completed, cancelled -- Başlangıç tarihi -- Deadline -- Bütçe veya beklenen gelir -- İlerleme yüzdesi, görevlerden otomatik hesaplanabilir veya manuel güncellenebilir - -MVP proje detay alanları: - -- Genel bakış: Projenin kısa özeti, mevcut durum ve önemli notlar -- Çözdüğü problem: Hangi kullanıcı/müşteri problemini çözdüğü -- Amaç ve başarı kriterleri: Proje bittiğinde neyin başarılı kabul edileceği -- Hedef kitle: Projenin kimin için yapıldığı -- Kapsam: Dahil olan ve dahil olmayan işler -- Design system: Renk paleti, tipografi, component notları ve görsel dil -- Renk paleti: Hex değerleri, kullanım rolleri ve notlar -- Tipografi: Font ailesi, başlık/gövde kullanımı ve hiyerarşi notları -- Görsel varlıklar: Kapak görseli ve proje içi görsel referanslar -- Serbest notlar: Projeye özel planlama notları - -MVP aksiyonları: - -- Proje ekleme -- Proje düzenleme -- Projeye bilgisayardan kapak görseli yükleme -- Proje detay sayfasında görev dışı planlama alanlarını yönetme -- Proje detayında design system alanları ekleme/düzenleme -- Projeye görev bağlama -- Proje durumunu güncelleme -- Projeyi tamamlandı olarak işaretleme - -Raporlar: - -- Aktif proje sayısı -- Geciken proje sayısı -- Proje bazlı görev tamamlama oranı -- Müşteri projeleri / side project dağılımı -- Design system alanı eksik olan aktif projeler -- Amaç veya problem tanımı eksik olan projeler - -MVP dışı: - -- Ekip üyeleri -- Gelişmiş dosya/drive yönetimi -- Kanban sprint sistemi -- Gelişmiş risk analizi - ---- - -### 4. Gorevler - -**Amac:** Freelancer'in gunluk operasyonunu yonetmek. - -MVP alanlari: - -- Baslik -- Aciklama -- Durum: todo, in_progress, done -- Oncelik: low, medium, high, urgent -- Son tarih -- Bagli proje -- Bagli musteri, proje uzerinden de turetilebilir -- Tahmini sure -- Gerceklesen sure, basit manuel giris olarak - -MVP aksiyonlari: - -- Gorev ekleme -- Gorev duzenleme -- Gorev tamamlama -- Liste ve basit kanban gorunumu -- Geciken gorevleri filtreleme - -Raporlar: - -- Haftalik tamamlanan gorev sayisi -- Duruma gore gorev dagilimi -- Oncelige gore gorev dagilimi -- Proje bazli acik gorevler - -MVP disi: - -- Team assignee -- Otomatik AI onceliklendirme -- Gelismis time tracking timer - ---- - -### 5. Takvim - -**Amac:** Deadline, toplanti, odak blogu ve kisisel etkinlikleri planlamak. - -MVP alanlari: - -- Baslik -- Baslangic tarihi/saati -- Bitis tarihi/saati -- Tur: meeting, focus, deadline, personal, finance -- Bagli musteri/proje/gorev -- Not - -MVP aksiyonlari: - -- Etkinlik ekleme -- Etkinlik duzenleme -- Aylik gorunum -- Yaklasan etkinlik listesi - -Raporlar: - -- Haftalik etkinlik dagilimi -- Odak bloklari / toplantilar orani -- Yaklasan deadline listesi - -MVP disi: - -- Google Calendar entegrasyonu -- Iki yonlu sync -- AI schedule optimization - ---- - -### 6. Finans - -**Amac:** Freelancer'in temel gelir, gider ve nakit akis durumunu takip etmesi. - -MVP alanlari: - -- Islem tipi: income, expense -- Tutar -- Para birimi -- Tarih -- Kategori -- Bagli musteri -- Bagli proje -- Aciklama -- Odeme durumu: planned, pending, paid, cancelled - -MVP aksiyonlari: - -- Gelir ekleme -- Gider ekleme -- Islem duzenleme -- Islem silme/arsivleme -- Aylik filtreleme - -Raporlar: - -- Aylik gelir -- Aylik gider -- Net kazanc -- Musteri bazli gelir -- Proje bazli gelir -- Kategori bazli gider - -MVP disi: - -- Fatura olusturma -- Vergi hesaplama -- Banka entegrasyonu -- Subscription tracking -- Coklu sirket/hesap - ---- - -### 7. Gunluk Mood / Energy - -**Amac:** Freelancer'in kisisel kapasitesini ve is performansiyla iliskisini takip etmek. - -MVP alanlari: - -- Tarih -- Mood skoru -- Energy skoru -- Kisa not -- Calisma memnuniyeti skoru, opsiyonel - -MVP aksiyonlari: - -- Gunluk kayit ekleme -- Kayit duzenleme -- Haftalik/aylik trend izleme - -Raporlar: - -- Mood trend -- Energy trend -- Energy ile tamamlanan gorev iliskisi -- Dusuk enerji gunlerinde geciken gorevler - -MVP disi: - -- AI duygu analizi -- Otomatik etiketleme -- Klinik/terapötik yorumlar - ---- - -### 8. AI Chatbot - -**Amac:** Kullanici, kendi kayitli verileri hakkinda genel sorular sorabilsin. - -MVP davranisi: - -- Son 7/30 gun gorevleri, projeleri, takvim etkinlikleri, finans kayitlari ve mood/energy verileri context olarak hazırlanır. -- Kullanici basit sorular sorar: - - "Bu hafta en cok hangi projeye zaman harcamisim?" - - "Hangi musterilerden odeme bekliyorum?" - - "Bu ay finansal durumum nasil?" - - "Geciken islerim neler?" - - "Enerjim dusukken hangi isler aksamis?" - -Teknik yaklasim: - -- MVP'de tam vector RAG sart degil. -- Ilk asama: veritabanindan ilgili ozet context olusturup modele gondermek. -- Provider opsiyonlari: Ollama local, OpenAI, Gemini, Groq. - -MVP disi: - -- Embedding tabanli gelismis RAG -- Modul ici AI butonlari -- Otomatik gorev/proje onerisinde bulunma -- Otomatik finans yorumu -- Otonom aksiyon alma - ---- - -## MVP Disi Birakilacaklar - -Asagidaki ozellikler ilk surume alinmayacak: - -- Ekip ve rol yonetimi -- Gelismis CRM pipeline -- Teklif ve sozlesme sistemi -- Fatura olusturma -- Banka veya odeme entegrasyonlari -- Dokuman/drive yonetimi -- PDF/PNG export -- Mobil uygulama -- Google Calendar sync -- Modul bazli AI otomasyonlari -- Gelismis RAG/vector search -- Bildirim sistemi - ---- - -## Teknik Mimari Karari - -### Onerilen MVP Stack - -- **Frontend:** Next.js App Router, React, TypeScript -- **UI:** Poyraz UI, Tailwind CSS v4, Recharts -- **Database:** PostgreSQL -- **Backend/Auth:** Supabase veya self-host edilebilir Supabase alternatifi -- **Local AI opsiyonu:** Ollama -- **Cloud AI opsiyonlari:** OpenAI, Gemini, Groq - -### UI Karari - -MVP tasarimi Poyraz UI ile light design olarak kurulacak. - -Mevcut dark shadcn/Radix agirlikli prototip tasarim sistemi MVP icin referans alinmayacak. Sayfalar Poyraz UI bilesenleri, `poyraz-ui/preset.css` token sistemi ve Poyraz UI semantic renkleri uzerinden yeniden insa edilecek. - -Gecis prensipleri: - -- Ilk hedef login, register ve sidebar gibi uygulama kabugu ekranlari. -- Daha sonra Faz 2'de her modul kendi CRUD akisi gelistirilirken Poyraz UI'a tasinacak. -- Light design varsayilan olacak. -- Dark mode MVP icin zorunlu degil; Poyraz UI destekledigi icin sonraki fazlarda eklenebilir. -- Eski UI bilesenleri sadece gecici olarak kullanilabilir; yeni sayfa ve moduller Poyraz UI ile yazilacak. - -### Neden Server-first? - -Mobil uygulama sonraki hedef oldugu icin verinin senkronize olabilecegi merkezi bir backend gerekir. Bu nedenle MVP'de ana kaynak PostgreSQL/Supabase olmali. - -Offline/local-first destek daha sonra eklenebilir: - -- IndexedDB cache -- Offline draft kayitlari -- Sync queue -- Conflict resolution - -MVP'de bu alan mimaride dusunulur, fakat ana risk haline getirilmez. - ---- - -## MVP Veri Modeli - -Minimum tablolar: - -- `profiles` -- `clients` -- `projects` -- `project_planning_sections` -- `tasks` -- `calendar_events` -- `finance_transactions` -- `daily_logs` -- `chat_sessions` -- `chat_messages` -- `app_settings` -- Supabase Storage bucket: `project-assets` - -Temel iliskiler: - -- `clients` -> `projects` -- `projects` -> `project_planning_sections` -- `projects` -> `tasks` -- `clients` -> `finance_transactions` -- `projects` -> `finance_transactions` -- `calendar_events` -> `clients`, `projects`, `tasks` opsiyonel -- `daily_logs` -> kullanici ve tarih -- `chat_messages` -> `chat_sessions` - ---- - -## Faz Plani - -### Faz 0: Stabilizasyon - -Amac: Mevcut prototipi build edilebilir ve gelistirilebilir hale getirmek. - -Isler: - -- Build hatalarini gidermek. -- Urun adini netlestirmek: `Cognis`. -- Encoding bozukluklarini temizlemek. -- Mock veri kullanan ekranlari isaretlemek. -- `user_settings` yerine `app_settings` semasini netlestirmek. -- Supabase SQL dosyalarini sira, dokumantasyon ve calistirma kaydi olan bir sisteme oturtmak. -- Mevcut `supabase/schema.sql` dosyasini ilk database baseline olarak kaydetmek. -- Her yeni SQL ekinde ilgili dokumani ve query log kaydini zorunlu hale getirmek. -- MVP disi ekranlari sidebar'dan gecici olarak kaldirmak veya "coming later" durumuna almak. - -Kabul kriteri: - -- `npm run build` basarili. -- Ana layout, auth ve dashboard sorunsuz acilir. -- MVP kapsamindaki moduller net gorunur. -- Database query sirasi `docs/database/query-order.md` icinde kayitlidir. -- Calistirilan SQL dosyalari `docs/database/query-log.md` icinde takip edilir. -- Ilk baseline olan `supabase/schema.sql` icin aciklayici dokuman vardir. - ---- - -### Faz 1: Veritabani ve Auth - -Amac: Freelancer OS icin gercek veri modelini kurmak. - -Isler: - -- `clients`, `projects`, `tasks`, `calendar_events`, `finance_transactions`, `daily_logs`, `app_settings` tablolarini olusturmak. -- RLS politikalari eklemek. -- Supabase migration dosyalarini repo icine almak. -- Seed/demo data script'i hazirlamak. -- Tek kullanici akisina uygun auth'u sade tutmak. - -Kabul kriteri: - -- Yeni tablolar Supabase'de calisir. -- Kullanici sadece kendi verisini gorur. -- Demo data ile dashboard beslenebilir. - -Faz 1 repo ciktisi: - -- Core schema migration: `supabase/migrations/0002_add_freelancer_os_core_tables.sql` -- Demo seed dosyasi: `supabase/seeds/0001_demo_freelancer_os_data.sql` -- Migration dokumani: `docs/database/0002-freelancer-os-core-tables.md` -- Seed dokumani: `docs/database/seed-0001-demo-freelancer-os-data.md` -- Query sirasi kaydi: `docs/database/query-order.md` - -Not: SQL dosyalari repo icinde hazirdir. Supabase ortaminda calistirildiktan sonra `docs/database/query-log.md` guncellenmelidir. - ---- - -### Faz 1.5: Poyraz UI Tasarim Sistemi Gecisi - -Amac: Mevcut koyu prototip tasarimindan ayrilip uygulama kabugunu Poyraz UI tabanli light design sistemine tasimak. - -Isler: - -- `poyraz-ui` paketini projeye eklemek. -- Global CSS icinde Poyraz UI preset importunu yapmak: `@import "poyraz-ui/preset.css";` -- Tailwind CSS v4 gereksinimini ve mevcut Tailwind yapisiyla uyumlulugu netlestirmek. -- Poyraz UI light tokenlarini varsayilan tasarim dili olarak ayarlamak. -- Mevcut shadcn/Radix agirlikli dark auth tasarimini Poyraz UI ile degistirmek. -- Login sayfasini Poyraz UI atoms/molecules ile yeniden kurmak. -- Register sayfasini Poyraz UI atoms/molecules ile yeniden kurmak. -- Dashboard shell ve sidebar'i Poyraz UI navigation/organism yaklasimina gore yeniden kurmak. -- Eski dark background, gradient, glow ve agir motion desenlerini uygulama kabugundan kaldirmak. -- Poyraz UI kullanim notlarini proje dokumantasyonuna baglamak. - -Kabul kriteri: - -- Login light design ile Poyraz UI bilesenleri kullanarak calisir. -- Register light design ile Poyraz UI bilesenleri kullanarak calisir. -- Sidebar ve temel dashboard shell Poyraz UI tasarim diliyle uyumludur. -- Uygulama varsayilan olarak light gorunur. -- `npm run build` basarili olur. - -Notlar: - -- Bu fazda modul ic sayfalarinin tamamini yeniden tasarlamak zorunlu degildir. -- Modul sayfalari Faz 2'de CRUD gelistirme sirasinda Poyraz UI'a tasinir. -- Poyraz UI rehberi: `poyraz-ui-usage-guide.md` - -Faz 1.5 repo ciktisi: - -- Poyraz UI paketi projeye eklendi. -- Tailwind CSS v4 ve `@tailwindcss/postcss` gecisi yapildi. -- Global CSS, `poyraz-ui/preset.css` ve light Poyraz tokenlariyla guncellendi. -- Login ve register sayfalari Poyraz UI atomlariyla yeniden kuruldu. -- Dashboard shell ve sidebar Poyraz UI organism yaklasimina tasindi. - ---- - -### Faz 2: Core CRUD Modulleri - -Amac: Freelancer'in temel operasyon verilerini girebilmesi. - -Isler: - -- Musteriler CRUD - - Liste, bos durum, ekleme/duzenleme formu ve detay gorunumu Poyraz UI ile kurulur. - - Eski CRM/prototip gorsel dili kaldirilir. -- Projeler/side project CRUD - - Proje kartlari, filtreler, detay paneli ve form akislari Poyraz UI ile kurulur. - - Musteri projesi ve side project ayrimi UI'da net gosterilir. - - Proje kapak gorseli bilgisayardan yuklenebilir; harici gorsel linki MVP icin ana akis olmaz. - - Proje detay sayfasi eklenir. - - Proje detayinda gorevler disinda planlama alanlari yonetilir: genel bakis, cozdugu problem, amac, hedef kitle, kapsam, design system, renk paleti, tipografi, gorsel varliklar ve notlar. - - Design system alaninda renk paleti, tipografi ve component/gorsel dil notlari eklenebilir ve duzenlenebilir. - - Proje detay sayfasi proje icin tek kaynak olur; gorevler sadece bu kaynak icindeki operasyon katmanidir. -- Gorevler CRUD - - Liste ve basit kanban Poyraz UI bilesenleriyle yeniden tasarlanir. - - Durum, oncelik, deadline ve proje iliskisi icin Poyraz UI Badge/Form/Select kullanilir. -- Takvim etkinlikleri CRUD - - Aylik gorunum ve yaklasan etkinlik listesi light design ile kurulur. - - Etkinlik formu Poyraz UI form bilesenleriyle yazilir. -- Finans islemleri CRUD - - Gelir/gider listesi, finans kartlari ve islem formu Poyraz UI ile kurulur. - - Rapor kartlari Poyraz UI StatsCard/Card yaklasimina uygun olur. -- Daily mood/energy CRUD - - Gunluk kayit formu, trend ozeti ve kayit listesi Poyraz UI ile kurulur. - - Mood/energy secimleri light, sade ve form odakli olur. - -Kabul kriteri: - -- Mock data yerine gercek veriler kullanilir. -- Her modulde liste, ekleme, duzenleme ve temel silme/arsivleme vardir. -- Bos durumlar kullaniciyi dogru aksiyona yonlendirir. -- Faz 2 kapsamindaki her yeni/yenilenen modul Poyraz UI bilesenleriyle yazilir. - ---- - -## Proje Detay MVP Planı - -Bu bölüm, Faz 2 içindeki Projeler/Side Project modülünün görev takibinden daha geniş bir proje yönetim alanına dönüşmesi için detaylı uygulama planıdır. - -### 1. Liste ve Oluşturma - -Amaç: Kullanıcı projeyi hızlıca oluşturabilsin ve görsel kimliğini ilk anda belirleyebilsin. - -Alanlar: - -- Proje adı -- Tür: müşteri projesi veya side project -- Bağlı müşteri -- Kapak görseli -- Kapak görseli alt metni -- Kısa açıklama -- Durum -- Başlangıç tarihi -- Deadline -- Bütçe / beklenen gelir -- İlerleme yüzdesi - -Davranış: - -- Görsel bilgisayardan seçilir ve `project-assets` bucket'ına yüklenir. -- Görsel yolu `projects.cover_image_path` alanında saklanır. -- Görsel link ile ekleme MVP akışı değildir. -- Görsel yüklenmezse proje kartında sade placeholder gösterilir. - -### 2. Proje Detay Sayfası - -Amaç: Proje ile ilgili görev dışı tüm planlama bilgisini tek merkezde yönetmek. - -Route önerisi: - -- `/projects/[id]` - -Ana bölümler: - -- Özet -- Planlama -- Design system -- Görevler -- Finans bağlantıları -- Zaman çizelgesi - -İlk MVP için zorunlu bölümler: - -- Özet -- Planlama -- Design system -- Görevler - -### 3. Özet Bölümü - -İçerik: - -- Kapak görseli -- Proje adı -- Müşteri veya side project etiketi -- Durum -- İlerleme -- Deadline -- Bütçe -- Kısa açıklama - -Amaç: - -- Kullanıcı projeye girdiğinde projenin ne olduğunu ve hangi durumda olduğunu ilk bakışta anlar. - -### 4. Planlama Bölümü - -Bu bölüm `project_planning_sections` tablosundan beslenir. - -MVP kategorileri: - -- Genel bakış (`overview`) -- Çözdüğü problem (`problem`) -- Amaç (`goal`) -- Hedef kitle (`audience`) -- Kapsam (`scope`) -- Notlar (`notes`) - -Her kategori için: - -- Başlık -- Açıklama / içerik -- Sıralama -- Opsiyonel metadata - -Kullanım: - -- Kullanıcı kategori ekleyebilir. -- Kullanıcı kategori düzenleyebilir. -- Kullanıcı kategori silebilir. -- Kategoriler proje detayında ayrı kartlar halinde gösterilir. - -### 5. Design System Bölümü - -Bu bölüm de `project_planning_sections` tablosunu kullanır. - -MVP kategorileri: - -- Design system (`design_system`) -- Renk paleti (`color_palette`) -- Tipografi (`typography`) -- Görsel varlıklar (`assets`) - -Design system alanları: - -- Genel görsel dil -- Kullanılacak UI kit veya referans sistem -- Component notları -- Spacing / radius / shadow notları - -Renk paleti alanları: - -- Renk adı -- Hex değeri -- Kullanım rolü: primary, secondary, accent, background, text, border -- Not - -Tipografi alanları: - -- Font ailesi -- Başlık kullanımı -- Gövde metni kullanımı -- Boyut/hiyerarşi notları - -MVP yaklaşımı: - -- İlk sürümde renk paleti ve tipografi structured JSON metadata içinde tutulabilir. -- UI tarafında bu metadata sade form alanlarıyla düzenlenir. -- Gerekirse MVP sonrası `project_colors` ve `project_typography_tokens` gibi ayrı tablolara bölünebilir. - -### 6. Görevler Bölümü - -Amaç: - -- Projeye bağlı görevleri proje detayından da yönetebilmek. - -MVP kapsamı: - -- Projeye bağlı görevleri listeleme -- Yeni görev ekleme -- Görev durumunu güncelleme -- Görevi tamamlandı işaretleme - -Bu bölüm görev modülüyle aynı veriyi kullanır; ayrı bir görev sistemi kurulmaz. - -### 7. Görsel Varlık Yönetimi - -MVP kapsamı: - -- Proje kapak görseli yükleme -- Kapak görselini değiştirme -- Kapak görseli alt metni düzenleme - -MVP dışı: - -- Çoklu dosya klasör yapısı -- Versiyonlama -- Dosya yorumları -- Gelişmiş medya kütüphanesi - -Storage kuralı: - -- Bucket: `project-assets` -- Path: `/projects//` -- Bucket private olur. -- Uygulama görsel gösterirken signed URL üretir. - -### 8. Uygulama Sırası - -1. Database migration: `0003_add_project_planning_assets.sql` -2. Proje formuna kapak görseli yükleme alanı ekle -3. Proje kartlarında kapak görseli göster -4. `/projects/[id]` detay sayfasını oluştur -5. Proje detay özet bölümünü gerçek veriyle kur -6. `project_planning_sections` CRUD action'larını ekle -7. Planlama bölümü kartlarını ekle -8. Design system bölümünü ekle -9. Projeye bağlı görevler bölümünü detay sayfasına bağla -10. Dashboard raporlarında design system/problem/amaç eksikliği gibi proje sağlık sinyallerini kullan - -### 9. Kabul Kriterleri - -- Kullanıcı proje oluştururken bilgisayarından kapak görseli yükleyebilir. -- Proje kartında ve detay sayfasında kapak görseli görünür. -- Kullanıcı proje detayında görevler dışında proje planlama alanlarını yönetebilir. -- Kullanıcı design system, renk paleti ve tipografi notlarını ekleyebilir. -- Tüm veriler kullanıcı bazlı RLS ile korunur. -- `npm run build` başarılı olur. - ---- - -### Faz 3: Dashboard ve Raporlama - -Amac: Girilen verileri anlamli grafiklere ve rapor kartlarina donusturmek. - -Isler: - -- Dashboard KPI kartlari -- Gorev tamamlama grafikleri -- Proje ilerleme grafikleri -- Musteri/proje bazli gelir ozeti -- Gelir/gider/net kazanc grafigi -- Mood/energy trendleri -- Yaklasan deadline ve odeme listeleri - -Kabul kriteri: - -- Dashboard tamamen gercek veriden beslenir. -- Her MVP modulu en az bir anlamli rapor/grafik sunar. -- Tarih filtresi: bugun, bu hafta, bu ay. - ---- - -### Faz 4: Basit AI Chatbot - -Amac: Kullanici kendi freelancer verileri hakkinda soru sorabilsin. - -Isler: - -- Chat UI'i stabil hale getirmek. -- Provider secimi: Ollama, OpenAI, Gemini, Groq. -- Son 7/30 gun verilerinden context builder yazmak. -- Chat mesajlarini kaydetmek. -- AI cevaplarini "danisma/asistan" sinirinda tutmak. - -Kabul kriteri: - -- Kullanici kayitli verileri hakkinda soru sorabilir. -- Chatbot en az gorev, proje, musteri, finans ve daily log ozetlerini context olarak kullanir. -- AI calismasa bile uygulamanin temel modulleri calismaya devam eder. - ---- - -### Faz 5: Self-host Hazirligi - -Amac: Projeyi acik kaynak ve self-host edilebilir hale getirmek. - -Isler: - -- `.env.example` hazirlamak. -- Kurulum dokumani yazmak. -- Migration calistirma adimlarini belgelemek. -- Docker Compose opsiyonunu degerlendirmek. -- Demo kullanici/demo data akisi eklemek. - -Kabul kriteri: - -- Yeni bir gelistirici dokumana bakarak projeyi ayaga kaldirabilir. -- Harici AI servisleri opsiyonel kalir. -- Local Ollama ile temel AI deneyimi mumkundur. - ---- - -## MVP Sonrasi Fazlar - -### Faz 6: Freelancer Business OS - -- Teklifler -- Sozlesmeler -- Fatura olusturma -- Odeme takip otomasyonlari -- Vergi/kar tahmini -- Abonelik ve masraf yonetimi - -### Faz 7: Gelismis CRM - -- Lead pipeline -- Musteri aktiviteleri -- Follow-up hatirlatmalari -- Musteri degeri ve risk raporlari - -### Faz 8: Gelismis AI - -- Embedding tabanli RAG -- Modul ici AI onerileri -- Akilli onceliklendirme -- Finansal yorumlama -- Takvim optimizasyonu -- Proje risk tahmini - -### Faz 9: Mobil ve Sync - -- Mobil uygulama -- Offline cache -- Push notification -- Takvim ve gorev sync -- Local-first deneyim iyilestirmeleri - ---- - -## MVP Basari Kriterleri - -MVP basarili sayilirsa: - -- Freelancer gunluk islerini, musterilerini, projelerini, side project'lerini ve temel finansini tek yerde takip edebilir. -- Dashboard gercek verilerle anlamli haftalik/aylik raporlar sunar. -- Kullanici uygulamayi self-host edebilir. -- AI chatbot opsiyonel ama kullanisli bir danisma katmani olarak calisir. -- Uygulama tek kullanici icin guvenilir ve build edilebilir durumdadir. diff --git a/docs/database/0001-initial-schema.md b/docs/database/0001-initial-schema.md deleted file mode 100644 index 2243cf7..0000000 --- a/docs/database/0001-initial-schema.md +++ /dev/null @@ -1,60 +0,0 @@ -# 0001 Initial Schema - -SQL file: `supabase/schema.sql` - -## Purpose - -This is the first registered database query file for the project. It represents the schema that existed before the Freelancer OS MVP planning work started. - -## What It Creates - -- `journals` -- `tasks` -- `chat_sessions` -- `chat_messages` -- `profiles` -- Row Level Security policies for the tables above -- `handle_new_user()` trigger function for profile creation -- `on_auth_user_created` trigger -- `avatars` storage bucket and related storage policies - -## Current Product Fit - -This schema supports the earlier MindSpace/Cognis prototype: - -- mood/energy journals -- basic tasks -- chat history -- user profile storage -- avatar uploads - -It does not yet fully match the Freelancer OS MVP model. - -## Known Gaps For MVP - -The Freelancer OS MVP still needs new schema additions for: - -- `clients` -- `projects` -- `calendar_events` -- `finance_transactions` -- `daily_logs` -- `app_settings` - -The existing `journals` table can either be migrated into `daily_logs` or kept as a legacy table until the UI is moved to the new model. - -## Execution Notes - -This file should be treated as the first baseline. - -It was updated to be safer for Supabase SQL Editor retries: - -- tables use `create table if not exists` -- policies are dropped before being recreated -- the profile trigger is dropped before being recreated -- the PL/pgSQL function uses the correct `$$` delimiter -- profile creation uses `on conflict (id) do nothing` - -If a previous run failed halfway through, rerunning this baseline should be safe for the current schema shape. - -Future changes should be added as ordered migration files rather than editing this baseline after execution. diff --git a/docs/database/0002-freelancer-os-core-tables.md b/docs/database/0002-freelancer-os-core-tables.md deleted file mode 100644 index 812d276..0000000 --- a/docs/database/0002-freelancer-os-core-tables.md +++ /dev/null @@ -1,72 +0,0 @@ -# 0002 Freelancer OS Core Tables - -SQL file: `supabase/migrations/0002_add_freelancer_os_core_tables.sql` - -## Purpose - -Adds the database model required for the Freelancer OS MVP. - -This migration keeps the existing baseline from `supabase/schema.sql` and extends it instead of replacing it. The existing `tasks` table is reused and enriched with freelancer-specific fields. - -## What It Creates - -- `clients` -- `projects` -- `calendar_events` -- `finance_transactions` -- `daily_logs` -- `app_settings` -- `set_updated_at()` trigger function -- updated-at triggers for the new tables -- indexes for common dashboard/report queries -- RLS policies for every new table - -## What It Changes - -The existing `tasks` table gets these additional columns: - -- `client_id` -- `project_id` -- `priority` -- `due_at` -- `estimated_minutes` -- `actual_minutes` - -This lets a task belong to a client and/or project while preserving the earlier journal/task prototype schema. - -## MVP Coverage - -This migration supports: - -- client management -- client projects -- side projects -- task planning -- calendar planning -- income and expense tracking -- daily mood/energy logging -- app and AI provider settings - -## RLS Model - -Every new table has `user_id`. - -Policies follow the same pattern: - -- users can select their own rows -- users can insert rows only for themselves -- users can update their own rows -- users can delete their own rows - -## Notes - -`app_settings.api_key` exists for compatibility with the current prototype flow. For production-grade use, provider credentials should be encrypted or moved to a safer secret-management strategy. - -`daily_logs` is the new MVP-oriented replacement for the earlier `journals` concept. The old `journals` table remains available until the UI migration is complete. - -## Execution - -Run this after `supabase/schema.sql`. - -Do not add this file to `query-log.md` until it has actually been executed against a database. - diff --git a/docs/database/0003-project-planning-assets.md b/docs/database/0003-project-planning-assets.md deleted file mode 100644 index 55a7ede..0000000 --- a/docs/database/0003-project-planning-assets.md +++ /dev/null @@ -1,92 +0,0 @@ -# 0003 - Project Planning Assets - -SQL file: `supabase/migrations/0003_add_project_planning_assets.sql` - -## Purpose - -This migration extends project management beyond task tracking. - -It adds: - -- Project cover image fields on `projects` -- A private Supabase Storage bucket for uploaded project images -- A structured `project_planning_sections` table for project planning categories - -## Project Image Fields - -The `projects` table receives: - -- `cover_image_path`: path of the uploaded file in the `project-assets` bucket -- `cover_image_alt`: optional alt text for the cover image - -Images are uploaded from the user's computer, not saved as external image links. - -## Storage Bucket - -Bucket: - -- `project-assets` - -Configuration: - -- Private bucket -- Max file size: 5 MB -- Allowed MIME types: - - `image/jpeg` - - `image/png` - - `image/webp` - - `image/gif` - -Storage object paths must start with the authenticated user id: - -```txt -/projects// -``` - -This keeps Storage RLS simple and user-scoped. - -## Planning Sections - -Table: - -- `project_planning_sections` - -Core fields: - -- `user_id` -- `project_id` -- `category` -- `title` -- `content` -- `metadata` -- `sort_order` - -Allowed categories: - -- `overview` -- `problem` -- `goal` -- `audience` -- `scope` -- `design_system` -- `color_palette` -- `typography` -- `assets` -- `notes` - -## RLS - -RLS is enabled for `project_planning_sections`. - -Users can only select, insert, update, and delete their own planning sections. - -Storage policies allow users to select, upload, update, and delete only files under their own user id folder inside `project-assets`. - -## Execution - -Run after: - -1. `supabase/schema.sql` -2. `supabase/migrations/0002_add_freelancer_os_core_tables.sql` - -After running this SQL in Supabase, add an execution record to `docs/database/query-log.md`. diff --git a/docs/database/0009-lock-registration-after-first-admin.md b/docs/database/0009-lock-registration-after-first-admin.md deleted file mode 100644 index 3853c04..0000000 --- a/docs/database/0009-lock-registration-after-first-admin.md +++ /dev/null @@ -1,34 +0,0 @@ -# 0009 - Lock Registration After First Admin - -SQL file: - -`supabase/migrations/0009_lock_registration_after_first_admin.sql` - -## Purpose - -Adds the first-time setup guard for self-hosted installations. - -The `/register` page is only available while the system has no profile record. After the first account creates a profile, public registration is closed. - -## Changes - -- Adds `public.is_first_admin_setup_available()`. -- Grants the function to `anon` and `authenticated` roles so the app can check setup state safely without bypassing RLS manually. -- Replaces `public.handle_new_user()` so direct public Supabase Auth signup attempts are also rejected after the first profile exists. -- Allows service-role/admin-created users when `raw_app_meta_data.internal_created` is `true`, so future invite/client-portal flows can still create accounts intentionally. - -## Behavior - -1. Fresh install has no `public.profiles` rows. -2. `/register` stays open. -3. The first signup creates an auth user and the trigger creates the first profile. -4. The setup function starts returning `false`. -5. `/register` redirects to `/login`. -6. Further public signup attempts fail at the database trigger level. -7. Admin-created internal users can still be allowed by service-role flows that set `app_metadata.internal_created = true`. - -## Notes - -- This is intended for the MVP single-admin self-host model. -- If multi-user, client portal accounts, invites, or team members are re-enabled later, keep them behind service-role/admin-created flows instead of public signup. -- Do not add this SQL file to `query-log.md` until it has actually been run in the target Supabase environment. diff --git a/docs/database/README.md b/docs/database/README.md deleted file mode 100644 index f714ebc..0000000 --- a/docs/database/README.md +++ /dev/null @@ -1,44 +0,0 @@ -# Database Change Process - -This directory records every database change that should be run against Supabase/PostgreSQL. - -The project currently starts with `supabase/schema.sql` as the first database query file. Future database changes must be added as separate SQL files and registered here before they are run. - -## Rules - -1. Every SQL change must have a stable order number. -2. Every SQL file must be listed in `query-order.md`. -3. Every executed query must be recorded in `query-log.md`. -4. Every meaningful schema addition must have a short documentation file under this directory. -5. Do not edit an already executed SQL file silently. Add a new ordered SQL file instead. - -## Current Files - -- `supabase/schema.sql`: Initial legacy schema. It creates the current auth/profile, journal, task, chat, and avatar storage structure. -- `supabase/migrations/0002_add_freelancer_os_core_tables.sql`: Freelancer OS MVP core schema. -- `supabase/seeds/0001_demo_freelancer_os_data.sql`: Optional local/demo data for the MVP schema. -- `docs/database/0001-initial-schema.md`: Explanation for the initial schema. -- `docs/database/0002-freelancer-os-core-tables.md`: Explanation for the MVP schema migration. -- `docs/database/seed-0001-demo-freelancer-os-data.md`: Explanation for the demo seed file. -- `docs/database/query-order.md`: Canonical order of SQL files. -- `docs/database/query-log.md`: Manual execution log for SQL files that were run against an environment. - -## Next Migration Naming - -Use this pattern for future SQL files: - -```text -supabase/migrations/0002_short_description.sql -``` - -Example: - -```text -supabase/migrations/0002_add_freelancer_os_core_tables.sql -``` - -Use this pattern for future seed files: - -```text -supabase/seeds/0002_short_description.sql -``` diff --git a/docs/database/query-log.md b/docs/database/query-log.md deleted file mode 100644 index c680c29..0000000 --- a/docs/database/query-log.md +++ /dev/null @@ -1,10 +0,0 @@ -# Database Query Log - -This file records SQL files that were executed against a database environment. - -Do not mark a query as executed unless it was actually run. - -| Date | Environment | Order | SQL file | Runner | Result | Notes | -| --- | --- | --- | --- | --- | --- | --- | -| Not recorded | Unknown existing environment | 0001 | `supabase/schema.sql` | Unknown | Assumed existing baseline | File existed before this query log was introduced. Confirm manually before rerunning. | - diff --git a/docs/database/query-order.md b/docs/database/query-order.md deleted file mode 100644 index 5023397..0000000 --- a/docs/database/query-order.md +++ /dev/null @@ -1,25 +0,0 @@ -# Database Query Order - -This file is the canonical order of SQL files for database setup and migration. - -| Order | SQL file | Documentation | Status | -| --- | --- | --- | --- | -| 0001 | `supabase/schema.sql` | `docs/database/0001-initial-schema.md` | Baseline registered | -| 0002 | `supabase/migrations/0002_add_freelancer_os_core_tables.sql` | `docs/database/0002-freelancer-os-core-tables.md` | Pending execution | -| 0003 | `supabase/migrations/0003_add_project_planning_assets.sql` | `docs/database/0003-project-planning-assets.md` | Pending execution | -| 0009 | `supabase/migrations/0009_lock_registration_after_first_admin.sql` | `docs/database/0009-lock-registration-after-first-admin.md` | Pending execution | -| seed-0001 | `supabase/seeds/0001_demo_freelancer_os_data.sql` | `docs/database/seed-0001-demo-freelancer-os-data.md` | Optional demo seed, pending execution | - -## How To Add The Next Query - -1. Create a new SQL file under `supabase/migrations/`. -2. Use the next order number. -3. Add a documentation file under `docs/database/`. -4. Register both files in this table. -5. After running the SQL, add an entry to `query-log.md`. - -## Seed Files - -Seed files are optional and should live under `supabase/seeds/`. - -They must also be documented and registered in this file, but they should only be run in local/demo environments unless explicitly approved. diff --git a/docs/database/seed-0001-demo-freelancer-os-data.md b/docs/database/seed-0001-demo-freelancer-os-data.md deleted file mode 100644 index fa2ee33..0000000 --- a/docs/database/seed-0001-demo-freelancer-os-data.md +++ /dev/null @@ -1,43 +0,0 @@ -# Seed 0001 Demo Freelancer OS Data - -SQL file: `supabase/seeds/0001_demo_freelancer_os_data.sql` - -## Purpose - -Adds demo data for local development and dashboard testing after the Freelancer OS core tables are created. - -## What It Inserts - -- demo clients -- demo projects and one side project -- demo tasks -- demo calendar events -- demo finance transactions -- demo daily mood/energy logs -- demo `app_settings` - -## Required Manual Step - -Before running the file, replace this placeholder with a real `auth.users.id`: - -```sql -'00000000-0000-0000-0000-000000000000'::uuid -``` - -Use a user id from your Supabase Auth users table. - -## Environment - -This seed is intended for local and demo environments only. - -Do not run it on production data. - -## Execution - -Run after: - -1. `supabase/schema.sql` -2. `supabase/migrations/0002_add_freelancer_os_core_tables.sql` - -After running it, add an entry to `docs/database/query-log.md`. - diff --git a/poyraz-ui-usage-guide.md b/poyraz-ui-usage-guide.md deleted file mode 100644 index d13315f..0000000 --- a/poyraz-ui-usage-guide.md +++ /dev/null @@ -1,413 +0,0 @@ -# Poyraz UI - Usage Guide (Detayli) - -Bu dokuman, `d:/Poyraz/kodlama/poyraz-ui` reposunun guncel kaynak kodu uzerinden hazirlandi. -Hedef: UI kitin hem kullanici (consumer) tarafini hem de bu repoyu gelistirme tarafini tek yerde toplamak. - -Versiyon referansi: `2.0.1` - ---- - -## 1) Proje Ozeti - -Poyraz UI, React tabanli, Tailwind CSS v4 ile calisan, atomic design yaklasimi kullanan bir UI kit. -Repo iki ana amaca hizmet ediyor: - -1. npm paketi olarak dagitilan UI kutuphanesi (`src`, `components/ui`, `dist`) -2. Next.js App Router ile yazilmis canli dokumantasyon sitesi (`app`) - -Temel karakter: - -- clean border odakli, minimum shadow -- `rounded-sm` kullanimina dayali yalin gorunum -- semantic token sistemi (`--poyraz-*`) -- dark mode uyumlu -- atoms -> molecules -> organisms katmanlamasi - ---- - -## 2) Dizin Yapisi (Gercek Kod Yapisi) - -```txt -poyraz-ui/ -|- app/ # Next.js docs sitesi -| |- docs/ # component/template dokumantasyon sayfalari -| |- globals.css # docs sitesi global css + dark override -| |- layout.tsx # next-themes + Toaster entegrasyonu -| `- page.tsx # landing/showcase -|- bin/ -| `- cli.mjs # npx poyraz-ui init -|- components/ -| |- ui/ -| | |- atoms/ # 17 atom dosyasi -| | |- molecules/ # 22 molecule dosyasi -| | `- organisms/ # 5 organism dosyasi -| |- theme-provider.tsx # docs sitesi next-themes wrapper -| `- theme-toggle.tsx # docs sitesi toggle -|- lib/ -| `- navigation.ts # docs nav/registry merkezi config -|- src/ -| |- index.ts # ana export -| |- atoms/index.ts # atom export map -| |- molecules/index.ts # molecule export map -| |- organisms/index.ts # organism export map -| |- themes/index.ts # poyrazLightTheme / poyrazDarkTheme -| |- preset.css # token layer + @theme bridge -| `- utils.ts # cn() -|- dist/ # tsup output (publish edilen paket) -|- tsup.config.ts # 5 entry point, esm+cjs, dts -`- package.json -``` - ---- - -## 3) Kullanici Tarafi Kurulum (Consumer App) - -### 3.1 Paket kurulumu - -```bash -pnpm add poyraz-ui -# veya -npm install poyraz-ui -# veya -yarn add poyraz-ui -``` - -### 3.2 Zorunlu peer dependencies - -- `react >= 18` -- `react-dom >= 18` -- `tailwindcss >= 4` - -Opsiyonel peer dependencies: - -- `react-hook-form`, `@hookform/resolvers`, `zod` (Form molecule icin) -- `reactive-switcher` (hazir theme objectleriyle dinamik tema gecisi icin) - -### 3.3 CSS import (kritik) - -Root global stylesheet dosyana ekle: - -```css -@import "tailwindcss"; -@import "poyraz-ui/preset.css"; -``` - -`preset.css` olmadan renk/font tokenlari dogru resolve edilmez. - -### 3.4 Hemen kullanim - -```tsx -import { Button, Card, CardContent } from "poyraz-ui/atoms"; - -export function Demo() { - return ( - - - - - - ); -} -``` - ---- - -## 4) Import Stratejisi ve Entry Pointler - -Paket 5 entry point sunuyor: - -- `poyraz-ui` -- `poyraz-ui/atoms` -- `poyraz-ui/molecules` -- `poyraz-ui/organisms` -- `poyraz-ui/themes` - -Onerilen yaklasim: - -- Uretim projelerinde alt path importlarini kullan (`/atoms`, `/molecules`, `/organisms`) -- Gecis surecinde hiz icin ana barrel (`poyraz-ui`) kullanabilirsin - -Ornek: - -```tsx -import { Button, Badge } from "poyraz-ui/atoms"; -import { Dialog } from "poyraz-ui/molecules"; -import { Navbar } from "poyraz-ui/organisms"; -import { poyrazLightTheme, poyrazDarkTheme } from "poyraz-ui/themes"; -``` - ---- - -## 5) Tema Sistemi (En Onemli Altyapi) - -Tema zinciri su sekilde calisiyor: - -1. Component classlari `bg-background`, `text-foreground`, `border-border` gibi semantic utility kullaniyor. -2. `src/preset.css`, `@theme` ile bunlari `--color-*` tokenlarina bagliyor. -3. `--color-*` tokenlari, `var(--poyraz-*, fallback)` ile semantic CSS variable'a mapleniyor. -4. Sen `--poyraz-*` degistirdiginde tum kit yeni temaya gecer. - -### 5.1 Token katmanlari - -- Base semantic variables: `--poyraz-background`, `--poyraz-foreground`, `--poyraz-primary`, ... -- Tailwind v4 bridge: `--color-background`, `--color-foreground`, ... -- Utility kullanim: `bg-background`, `text-muted-foreground`, ... - -### 5.2 Dark mode (class tabanli) - -Docs sitesi `next-themes` kullaniyor ve `html.dark` altinda `--poyraz-*` override ediyor (`app/globals.css`). - -### 5.3 reactive-switcher entegrasyonu - -`src/themes/index.ts` icinde hazir theme objectleri var: - -- `poyrazLightTheme` -- `poyrazDarkTheme` -- `poyrazThemes` - -Ornek: - -```tsx -import { ThemeProvider } from "reactive-switcher"; -import { poyrazThemes } from "poyraz-ui/themes"; - -export function AppTheme({ children }: { children: React.ReactNode }) { - return {children}; -} -``` - ---- - -## 6) Component Katalogu - -Bu bolum `src/*/index.ts` export maplerine gore hazirlandi. - -### 6.1 Atoms (17 component dosyasi) - -- Avatar -- Badge -- Button -- Card -- Checkbox -- Input -- Label -- Logo -- Radio Group -- Separator -- Skeleton -- Switch -- Textarea -- Typography -- Form Fields (`NumberInput`, `SearchInput`, `PhoneInput`, `PasswordInput`, `UrlInput`) -- BG Patterns (`PatternDots`, `PatternGrid`, `PatternLines`, `PatternDiagonal`, `PatternCross`, `PatternCheckerboard`, `PatternDiamond`, `PatternZigzag`, `PatternDashedGrid`, `PatternRadial`) -- ScrollArea - -### 6.2 Molecules (22 component dosyasi) - -Core molecules: - -- Accordion -- Alert -- Autocomplete -- Breadcrumb -- Calendar -- Command Palette -- Date Picker -- Dialog -- Drawer -- Dropdown Menu -- Form -- Hover Card -- Modal -- Pagination -- Popover -- Select -- Sheet -- Sonner (`Toaster`, `toast`) -- Tabs -- Tooltip - -Template molecules (card-templates): - -- ArticleCard -- ImageCard -- NewsCard -- StatsCard -- TestimonialCard -- PricingCard -- ProductCard - -### 6.3 Organisms (5 component dosyasi) - -- Navbar -- Sidebar -- Footer -- AnnouncementBar -- DataTable - ---- - -## 7) Hazir Template Sayfalari (Docs Icinde) - -`app/docs/templates` altinda 4 kopyalanabilir sayfa semasi var: - -- Hero -- Pricing -- Dashboard -- Auth - -Onemli not: - -- Bunlar npm paketi icinde "template component" olarak export edilmiyor. -- Kaynagi kopyalayip projenin ihtiyacina gore duzenleme modeli kullaniliyor. - ---- - -## 8) Dokumantasyon Sitesi Mimarisi - -`app/docs` altinda: - -- toplam `53` adet `page.tsx` -- atoms: `18` -- molecules: `22` -- organisms: `6` -- templates: `5` - -Merkezi nav/registry: - -- `lib/navigation.ts` -- sidebardaki kategori sayilari ve slug donusumu burada yonetiliyor (`toSlug`) - ---- - -## 9) CLI: `npx poyraz-ui init` - -CLI (`bin/cli.mjs`) su adimlari yapar: - -1. CSS dosyasini otomatik tespit eder (`app/globals.css`, `src/app/globals.css` vb.) -2. `@import "poyraz-ui/preset.css";` satirini ekler -3. Opsiyonel olarak `reactive-switcher` tema dosyasi scaffold eder -4. Layout icin ThemeProvider snippet'i gosterir - -Manual kurulum yerine hizli onboarding icin ideal. - ---- - -## 10) Build, Bundle ve Publish Akisi - -### 10.1 Scriptler - -- `pnpm dev`: docs sitesi -- `pnpm build`: library + docs production build -- `pnpm build:lib`: sadece library (`tsup`) -- `pnpm start`: next production serve -- `pnpm prepublishOnly`: publish oncesi otomatik `build:lib` - -### 10.2 tsup ozeti - -`tsup.config.ts`: - -- 5 entry point uretir (`index`, `atoms/index`, `molecules/index`, `organisms/index`, `themes/index`) -- format: `esm + cjs` -- `dts: true` -- `splitting + treeshake + clean` -- build sonrasi `dist` dosyalarina `"use client"` directive inject eder - -### 10.3 package export haritasi - -`package.json` `exports` alani: - -- alt path importlarini hem ESM hem CJS ile aciklar -- `./preset.css` dogrudan `src/preset.css`'e yonlenir - ---- - -## 11) Bu Repoda Yeni Component Ekleme Rehberi - -### 11.1 Kod ekleme - -1. Component dosyasini `components/ui//` altina ekle -2. Gerekirse type exportlarini component dosyasinda tanimla - -### 11.2 Export haritasi - -3. `src//index.ts` icine export satirlarini ekle -4. Gerekliyse `src/index.ts` ana barrel kontrol et - -### 11.3 Docs entegrasyonu - -5. `app/docs///page.tsx` olustur -6. Kategori index sayfasina link ekle (`app/docs//page.tsx`) -7. `lib/navigation.ts` icindeki `componentRegistry` listesine ekle - -### 11.4 Dogrulama - -8. `pnpm build:lib` -9. `pnpm dev` ile docs sayfasini ve importlarini test et - ---- - -## 12) Sik Kullanilan Kullanim Patternleri - -### 12.1 Form stack - -- Atoms: `Input`, `Label`, `Checkbox`, `Button` -- Molecules: `Form`, `Select`, `DatePicker`, `Autocomplete` - -### 12.2 Overlay stack - -- `Dialog`, `Modal`, `Drawer`, `Sheet`, `Popover`, `Tooltip` -- Her biri Radix/Vaul primitive uzerinden geldigi icin a11y ve keyboard destegi yuksek - -### 12.3 Navigation stack - -- `Navbar` (desktop + mobile panel) -- `Sidebar` (collapsible/floating/mini varyantlar) -- `Footer` (layout varyantlari) - -### 12.4 Data stack - -- `DataTable` + `Badge` + `Pagination` -- dashboard tarzinda `StatsCard`, `Card`, `Avatar` ile birlikte kullaniliyor - ---- - -## 13) Bilinen Durumlar / Dikkat Noktalari - -1. `Mermaid` dokumantasyon sayfasi var (`app/docs/molecules/mermaid/page.tsx`) ancak su anda `src/molecules/index.ts` icinden export edilmiyor. -2. `componentRegistry` molecules listesi ile molecules landing page listesi tam birebir degil (sidebar listesinde Mermaid yok). -3. Template sayfalari (Hero/Pricing/Dashboard/Auth) paket exportu degil; kopyala-ozellestir modeli. -4. Rehber ve README metinlerinde bilesen sayilari bazen farkli geciyor; son karar noktasi her zaman `src/*/index.ts` export mapidir. - ---- - -## 14) Hizli Referans - -### 14.1 Consumer app checklist - -1. `poyraz-ui` paketini kur -2. `@import "poyraz-ui/preset.css";` ekle -3. `poyraz-ui/atoms` veya `poyraz-ui/molecules` uzerinden import et -4. Tema gerekiyorsa `--poyraz-*` override et veya `poyraz-ui/themes` kullan - -### 14.2 Repo contributor checklist - -1. component dosyasi ekle (`components/ui`) -2. export map guncelle (`src/*/index.ts`) -3. docs page ekle (`app/docs/...`) -4. navigation registry guncelle (`lib/navigation.ts`) -5. `pnpm build:lib` ve `pnpm dev` ile dogrula - ---- - -## 15) Ek Kaynaklar - -- Paket genel tanitim: `README.md` -- Genis API referansi: `COMPONENTS.md` -- Theme switcher notlari: `theme-switcher.md` -- Kurulum sayfasi referansi: `app/docs/installation/page.tsx` - ---- - -Bu dokuman "proje ici operasyonel guide" amaciyla yazildi. -Paketin public-facing README'sini sade tutup, bu dosyayi teknik detay merkezi olarak kullanman tavsiye edilir.