Yeni Geliştirici Onboarding

Bu sayfa projeye yeni katılan developer’lar için ilk gün ve ilk hafta yol haritasını verir. Adımları tamamladığınızda yerelde uygulamanın ayağa kalkmış olması, dokümanların sırayla okunmuş olması ve ilk küçük değişikliğin yapılmış olması hedeflenir.

---

İlk gün checklist

Aşağıdaki adımları sırayla tamamlayın.

1. Repoyu klonlama

git clone https://github.com/techsider-co/coursio.git
cd coursio

2. Bağımlılıkları yükleme

npm install

3. Ortam dosyası: .dev.vars oluşturma

Proje kökünde .dev.vars dosyası oluşturun. Bu dosya git’e eklenmez (.gitignore).

En az şu değişkenleri ekleyin:

Değişken	Açıklama
DATABASE_URL	Neon PostgreSQL bağlantı dizesi
STRIPE_SECRET_KEY	Stripe test anahtarı (sk_test_...)
STRIPE_WEBHOOK_SECRET	Stripe CLI ile alınan whsec_... (yerel webhook için)
BETTER_AUTH_SECRET	Rastgele gizli anahtar (oturum şifreleme)

Detaylı liste ve örnek için Ortam Değişkenleri sayfasına bakın.

4. Uygulamayı ayağa kaldırma

npm run dev

• Uygulama http://localhost:5173 adresinde açılır.
• Tarayıcıda ana sayfayı açıp dil seçimi (ör. /tr) ile gezinebildiğinizi doğrulayın.

Not: API / webhook / DB testi için npm run start veya npx wrangler dev (port 8787) kullanılır; günlük UI geliştirme için npm run dev yeterlidir.

5. İlk sayfa değişikliği (footer metni)

Aşağıdaki “İlk değişiklik önerisi” bölümündeki senaryoyu uygulayarak footer’da küçük bir metin değişikliği yapın. Böylece dosya düzenleme → kaydetme → tarayıcıda görme döngüsünü tecrübe etmiş olursunuz.

---

Okuma sırası

Dokümanları aşağıdaki sırayla okuyun. Her sayfa bir sonrakine temel oluşturur.

Sıra	Sayfa	Amaç
1	Giriş (Proje Vizyonu & Tech Stack)	Projenin ne olduğu, LMS + pazaryeri vizyonu, kullanılan teknoloji yığını.
2	Yerel Kurulum Rehberi	Klonlama, npm install, .dev.vars, npm run dev adımları.
3	Ortam Değişkenleri	Tüm Secret ve Public anahtarların açıklamalı listesi; Stripe, Bunny, Better Auth, DB.
4	Geliştirme Akışı	Günlük komutlar (dev vs start), Stripe webhook yerelde test, build/deploy.
5	Proje Yapısı (Detaylı)	app/ altındaki klasörlerin görevi, route dosya isimlendirmesi, layout hiyerarşisi, ortak lib modülleri.
6	Route Haritası	Tüm URL’lerin özeti; public / auth / öğrenci / eğitmen / admin ayrımı, dil prefix kuralı.
7	İlgili mimari sayfalar	Yapacağınız işe göre: Veritabanı Şeması, API Referansı ve GraphQL, Checkout & Webhooks, Stripe Connect, Admin Console vb.

---

İlk değişiklik önerisi (ilk PR senaryosu)

Amaç: Küçük bir UI değişikliği yaparak dosya düzenleme → kaydetme → tarayıcıda doğrulama akışını tecrübe etmek.

Senaryo: Footer copyright metnini güncellemek

Yapılacak iş: Footer’daki “© 2026 Coursio, Inc.” metnini değiştirmek (örneğin metni kısaltmak veya bir ek metin eklemek).

Adımlar

1. Dosyayı açın: app/components/Footer.tsx
2. İlgili satırı bulun: Alt kısımda copyright metni şu şekilde yer alır:

   <span className="text-xs text-slate-500 font-medium">
     © 2026 Coursio, Inc.
   </span>

3. Değişiklik yapın: Örneğin metni © 2026 Coursio olarak kısaltın veya © 2026 Coursio — Geliştirme ortamı ekleyin.
4. Kaydedin ve tarayıcıda http://localhost:5173/tr (veya /en) sayfasını yenileyin.
5. Doğrulayın: Sayfayı aşağı kaydırarak footer’da yeni metni gördüğünüzü kontrol edin.

Hangi dosyaya dokunuldu?

Dosya	Açıklama
app/components/Footer.tsx	Footer bileşeni; copyright metni burada (satır ~149–151).

Nasıl test edilir?

• npm run dev çalışırken değişikliği kaydedin; HMR ile sayfa yenilenir.
• Dil sayfalarında (ör. /tr, /en) footer’ı kontrol edin; tüm dil sayfalarında aynı bileşen kullanılır.

Bu değişikliği bir branch açıp PR olarak gönderebilirsiniz (örn. fix: footer copyright metnini güncelle).

---

Sorun yaşandığında nereye bakılır?

Sorun	Bakılacak yer
Uygulama ayağa kalkmıyor, DB hatası	Ortam Değişkenleri — DATABASE_URL doğru mu? .dev.vars kökte mi?
Stripe webhook yerelde çalışmıyor	Geliştirme Akışı — stripe listen ve STRIPE_WEBHOOK_SECRET güncellemesi.
Giriş yapamıyorum / session kayboluyor	Ortam Değişkenleri — BETTER_AUTH_SECRET, BASE_URL / BETTER_AUTH_URL tutarlı mı?
Hangi komutu kullanacağım?	Geliştirme Akışı — dev (UI) vs start (API/DB).
Route / API nerede tanımlı?	app/routes.ts ve API Referansı ve GraphQL.
Veritabanı şeması / tablolar	Veritabanı Şeması ve app/db/schema.ts.
Yaygın hatalar (DB, Stripe, auth, Bunny, build, migration)	Hata Ayıklama ve Yaygın Sorunlar.

Hata ayıklama ve yaygın sorunlar için ayrı bir “Troubleshooting” kılavuzu detay için yukarıdaki tabloda “Yaygın hatalar” satırına bakın.

---

Özet

1. İlk gün: Repo klonla → npm install → .dev.vars oluştur → npm run dev → footer’da küçük bir metin değişikliği yapıp doğrula.
2. Okuma sırası: Giriş → Yerel Kurulum → Ortam Değişkenleri → Geliştirme Akışı → Proje Yapısı → Route Haritası → İlgili mimari sayfalar.
3. İlk PR: Footer copyright metnini Footer.tsx içinde güncelle; yerelde test edip PR aç.
4. Sorun: Hata Ayıklama ve Yaygın Sorunlar sayfasına bakın; gerekirse Ortam Değişkenleri, Geliştirme Akışı ve ilgili mimari sayfalarına yönlendirilirsiniz.

Bu adımları tamamladıktan sonra proje yapısı ve günlük akış hakkında temel bir fikre sahip olursunuz. Belirli bir özellik (ödeme, admin, eğitmen paneli vb.) üzerinde çalışacaksanız ilgili mimari sayfayı okuyun.