🎓 ORBIT — Eğitim Kurumu & Dershane Yönetim Platformu
ORBIT, 1–5 şubeli dershane, kurs merkezi ve eğitim kurumları için tasarlanmış; kurum yöneticisi, öğretmen, öğrenci ve veli rollerini tek bir modern çalışma alanında birleştiren yeni nesil eğitim CRM ve operasyon platformudur.
🚀 Projeye Genel Bakış ve Mimari
ORBIT; devamsızlık takibi, ders programı, deneme sınavı analizleri, veli iletişimi ve kayıt/ödeme operasyonlarını rol bazlı erişim modeli (RBAC) ile yönetir.
👥 Roller ve Çalışma Alanları
- 👑 Kurum Yöneticisi (Admin): Kurum genel özeti, öğrenci ve sınıf organizasyonu, yoklama takibi, sınav sonuçları ve sınıf karşılaştırması, kayıt ve ödeme takibi, raporlar ve ayarlar.
- 🧑🏫 Öğretmen (Teacher): Ders programı, hızlı yoklama alma, sınıf listeleri, sınav sonuçları, takip gereken öğrencilerin dikkat listesi ve duyurularla veli iletişimi.
- 🎒 Öğrenci (Student): Kişisel ders programı, ödev takibi, deneme sonuçları (ders ders doğru/yanlış/net ve sınıf ortalaması), kurum duyuruları ve öğretmenleriyle mesajlaşma.
- 👨👩👧 Veli (Parent): Öğrencinin devam durumu, son sınav karnesi, ödeme planı/taksit takibi ve kurum duyuruları.
🛠️ Teknoloji Yığını (Tech Stack)
| Katman | Teknoloji | Açıklama |
|---|
| Frontend | React + TypeScript + Vite | Maksimum tip güvenliği, hızlı derleme ve modüler SPA |
| Stil & Tasarım | Tailwind CSS + Radix UI + shadcn/ui | Erişilebilir headless bileşenler (components/ui/), modern tipografi |
| Yönlendirme | wouter | Hafif ve performanslı istemci yönlendirici |
| BaaS / Veri | @supabase/supabase-js | Doğrudan istemciden Supabase BaaS bağlantısı |
| State Yönetimi | @tanstack/react-query | Sunucu durumu senkronizasyonu |
| İkonlar & Bildirim | lucide-react, sonner | Tutarlı arayüz ikonları ve zengin bildirimler |
| Test | Vitest + pgTAP | Birim, yetkilendirme (RBAC) ve veritabanı politikası testleri |
| Paket Yöneticisi | pnpm | Hızlı ve disk tasarruflu paket yönetimi |
Sürüm numaraları burada tutulmuyor, package.json'da yaşıyor. Bu tablo bir süre sürüm de yazıyordu ve ayrıştı: 2026-09-19'da "Vitest 2.1" ve "TypeScript 5.9" yazarken kurulu olanlar 5.0 ve 6.0'dı. Aynı gerekçe aşağıdaki klasör ağacı için de geçerli — iki yerde tutulan bilginin biri her zaman eskir.
📁 Klasör Yapısı
client/src/ # React uygulaması — auth, platform paneli, dershane ekranları
supabase/ # Migration'lar, Edge Function'lar ve pgTAP testleri
.ai/ # Mimari kararlar, yol haritası ve platform ayarları
.github/ # CI iş akışları ve şablonlar
Dosya dosya ayrıntı — hangi modül ne yapar, hangi servis nerede yaşar — tek yerde tutulur:
.ai/PROJECT_STATE.md bölüm 5. Burada ikinci bir kopya tutulmuyor; iki ağaç bir süre sonra birbirini tutmuyor.
⚡ Yerel Kurulum (Geliştirici Rehberi)
ORBIT yerelde iki kipte açılır. Geliştirme gerçek kipte yapılır; demo kipi yalnız satış sunumu içindir.
| Kip | Ne çalışır | Ne zaman |
|---|
| Demo | Yalnız arayüz; veriler koda gömülü örneklerdir. Veritabanı, giriş, yetki (RLS) hiç çalışmaz | Ekrana hızlı bakmak, sunum |
| Gerçek | Bilgisayarındaki Supabase: veritabanı, giriş, RLS, Edge Function'lar, e-posta (sahte kutuya) | Her geliştirme ve her test |
Yerel kopya canlı sisteme (orbit-v3-kappa.vercel.app) hiç bağlanmaz. Yerelde her şeyi silip yeniden kurabilirsin; kimse etkilenmez.
Gerekenler
- Node 22+ (
.nvmrc) ve pnpm — corepack enable pnpm'i package.json'daki sürümle getirir.
- Docker Desktop — yerel Supabase Docker'da çalışır; kurulumdan önce açık olmalı.
- Supabase CLI — kurmak şart değil,
npx supabase … ile çalışır. CI 2.115.0 kullanır.
- Edge Function'ları denetlemek istersen Deno 2 (
deno check için; şart değil).
İlk kurulum (bir kez, ~15 dakika)
# 1. Bağımlılıklar
pnpm install
# 2. Edge Function'ların yerel ayarı (e-postalar yerel sahte kutuya düşer)
cp supabase/functions/.env.example supabase/functions/.env
# 3. Yerel Supabase'i başlat — ilk seferde Docker imajları iner (birkaç dakika).
# Göçlerin hepsi kendiliğinden uygulanır; veritabanı boş açılır.
npx supabase start
# 4. Örnek kurumu kur: operatör, yönetici, iki öğretmen, öğrenci, veli,
# 8 öğrenci, sınıflar, program, yoklama, sınav, ödeme, duyuru, mesaj.
pnpm yerel:tohum
Tohum, giriş numaralarını ekrana yazar. Bütün örnek hesapların şifresi Yerel-Orbit-2026 (yalnız yerel; ORBIT_YEREL_SIFRE ile değiştirilebilir). Operatör e-postayla girer: [email protected]. Tohum yerel olmayan bir adreste çalışmayı reddeder.
# 5. Arayüzü gerçek kipte bağla: kökte .env.local oluştur (git'e girmez)
npx supabase status -o env # API_URL ve ANON_KEY satırlarını al
# .env.local
VITE_DEPLOYMENT_ENV=production
VITE_SUPABASE_URL=http://127.0.0.1:54321
VITE_SUPABASE_ANON_KEY=<supabase status'taki ANON_KEY>
# 6. Aç
pnpm dev # http://localhost:5173
Gerçek kipte olduğunun kanıtı: giriş ekranında rol kartları ve "Demo şifresi" satırı görünmez; giriş numarası istenir. Demo kipine dönmek için .env.local'ı silmek ya da yeniden adlandırmak yeter (demo şifresi demo123).
⚠️ VERCEL_ENV değişkenini set etme. O varken vite.config.ts'in CSP kapısı devreye girer ve yerel adresle derleme durur (v1.5-09).
Günlük kullanım
| İş | Komut |
|---|
| Yığını başlat / durdur | npx supabase start / npx supabase stop (veri korunur) |
| Veritabanını sıfırla + örnek veri | npx supabase db reset && pnpm yerel:tohum |
| Gönderilen e-postaları gör | npx supabase status → Mailpit adresi (varsayılan http://127.0.0.1:54324) |
| Veritabanı panosu (Studio) | npx supabase status → Studio adresi (varsayılan http://127.0.0.1:54323) |
| Edge Function değişikliğini yükle | docker restart supabase_edge_runtime_orbit_v3 |
supabase/functions/.env değişikliği | npx supabase stop && npx supabase start |
Yeni bir göç yazdığında npx supabase db reset onu sıfırdan uygular; tohum betiği arayüzün kullandığı RPC ve Edge Function'lardan geçtiği için göç bir akışı bozarsa tohum da durur ve hangi adımda durduğunu söyler.
Testler — PR açmadan önce
pnpm format && pnpm check && pnpm lint && pnpm test # her PR (CI'daki quality-gate)
npx supabase test db # supabase/ değiştiyse: pgTAP
bash supabase/tests/functions/create_member_chain.sh # Edge Function değiştiyse
deno check supabase/functions/*/index.ts # Edge Function değiştiyse
pnpm build && node scripts/check-demo-leak.mjs # demo verisi üretim paketine sızdı mı
pgTAP ve zincir testi örnek veriden etkilenmez: her test dosyası kendi işleminde koşar ve yalnız o işlemde yazdığı satırları sayar (created_at >= now()). Yeni bir pgTAP iddiası tüm tabloyu sayıyorsa aynı süzgeci ekleyin; sabit giriş numarası gerekiyorsa 9000'li aralığı kullanın (örnek kurum 1000'den başlar).
Windows: supabase start port hatası verirse
Windows, Docker'ın kullanacağı bazı port aralıklarını kendine ayırabiliyor (Hyper-V/WinNAT). Belirti: supabase start "ports are not available" ya da "bind: An attempt was made to access a socket…" hatası. Ayrılmış aralıkları gör:
netsh interface ipv4 show excludedportrange protocol=tcp
543xx portlarından biri bir aralığın içindeyse supabase/config.toml'daki portları boş bir aralığa taşı (örn. 553xx: [api] port = 55321, [db] port = 55322, [studio] port = 55323, [local_smtp] port = 55324 …) ve bu değişikliği commit etme — yalnız senin makinene ait:
git update-index --skip-worktree supabase/config.toml # git artık bu dosyadaki yerel değişikliği görmez
.env.local'daki VITE_SUPABASE_URL da yeni API portunu göstermeli. Geri almak için: git update-index --no-skip-worktree supabase/config.toml && git checkout supabase/config.toml.
📋 Kullanılabilir Komutlar
| Komut | Açıklama |
|---|
pnpm dev | Vite geliştirme sunucusunu başlatır (.env.local yoksa demo kipi) |
pnpm build | Production derlemesi oluşturur (yalnızca Vite — tip kontrolü için ayrıca pnpm check çalıştırın) |
pnpm preview | Üretilen derlemeyi yerelde önizler |
pnpm check | TypeScript tip kontrollerini çalıştırır (tsc --noEmit) |
pnpm lint | ESLint ile kod kalitesi kontrollerini çalıştırır |
pnpm test | Vitest ile birim testlerini çalıştırır |
pnpm format | Prettier ile tüm kodları formatlar |
pnpm yerel:tohum | Boş yerel veritabanına örnek kurumu kurar (yalnız yerel adreste çalışır) |
🤝 Geliştirme ve Git Kuralları
Kurallar tek yerde yaşar: CONTRIBUTING.md. Özet — main'e doğrudan commit yok; her iş tür önekli bir dalda (fix/…, feat/…) PR olarak ilerler, bir insan onayıyla squash birleştirilir. YZ ajanları PR açar, birleştirmez.
YZ ajanlarıyla çalışma düzeni için .ai/AGENT_WORKFLOW.md, projeye giriş için kökteki AGENTS.md.
