Proje Yapısı (Detaylı)

Bu sayfa Achidemy projesinde app/ altındaki her klasörün görevini, route dosya isimlendirme kurallarını, layout hiyerarşisini ve ortak lib modüllerini tek yerde açıklar. Yeni dosya eklerken nereye koyacağınızı bu sayfadan takip edebilirsiniz.

---

Klasör Görevleri

Tüm uygulama kodu app/ kökü altındadır. Route tanımları proje kökündeki app/routes.ts dosyasındadır.

Klasör	Görev	Hangi dosyalar
app/routes/	Sayfa ve API route’ları. Her dosya bir URL path’e karşılık gelir; loader (veri) ve action (form/mutation) export edilir.	*.tsx (sayfa), api.*.ts (API), robots[.]txt.ts, sitemap[.]xml.ts
app/components/	Paylaşılan UI bileşenleri. Sayfa route’ları ve diğer bileşenler buradan import eder.	*.tsx; alt klasörler: ui/, instructor/, learn/, courses/, pricing/, teaching/, messages/. courses/ içinde keşfet bölümleri (BeginnerRecommendationsSection, FeaturedCoursesSection, PopularTopicsSection, PopularInstructorsSection), FilterSidebar, CourseReviews, CourseQA, CourseNotes vb.
app/lib/	Sunucu/istemci ortak yardımcı modüller: auth, DB sorguları, fiyat motoru, GraphQL client, video güvenliği, e-posta, Stripe vb.	*.ts (auth, db-queries, pricing-engine, graphql-client, video-security, env, email, stripe-connect-payout, payout-engine, streak, i18n, code-engine, invoice-pdf, moderation, utils, bunny, coupon-engine, exchange-rates, notifications vb.)
app/db/	Veritabanı şeması ve bağlantı. Drizzle ORM şeması ve getDb / migration ile ilgili kod.	schema.ts, index.ts, seed-pricing.ts
app/graphql/	GraphQL şema ve çözücüler. API /api/graphql bu şemayı kullanır.	schema.ts (typeDefs + resolvers)
app/locales/	i18n çeviri dosyaları. Dil kodu ile isimlendirilir.	tr.json, en.json, de.json, es.json, fr.json, ja.json vb.
app/hooks/	Paylaşılan React hook’ları. Route ve component’ler buradan import eder.	useLang.ts, useLearningTracker.ts, useChatNotifications.ts vb.

Kök dosyalar: app/root.tsx (uygulama kök bileşeni), app/routes.ts (route ağacı), app/app.css (global stil).

---

Route Dosya İsimlendirmesi

Route tanımları app/routes.ts içinde yapılır. Path’teki parametreler dosya adında $ ile yazılır; özel karakterler (örn. nokta) köşeli parantez ile escape edilir.

Path → Dosya Eşlemesi

Path (routes.ts)	Dosya (app/routes/)	Açıklama
route("path")	path.tsx	Sabit path.
route(":param")	$param.tsx	Tek parametre; dosya adında $ kullanılır.
route("course/:slug")	course.$slug.tsx	Çok segment; parametre $slug.
route("api/certificate/:id/download")	api.certificate.$id.download.ts	Nokta ile ayrılmış dosya adı; path’teki / → .
route("robots.txt")	robots[.]txt.ts	Literal nokta: [.]
route("sitemap.xml")	sitemap[.]xml.ts	Aynı kural.
route("*")	404.tsx (id ile)	Catch-all; genelde 404 sayfası.
index("routes/...")	_index.tsx veya root._index.tsx	Index route; segment adı _index.

Özet Kurallar

• Path’te :param → Dosya adında $param (örn. :slug → $slug, :id → $id).
• Path segment’leri dosya adında nokta (.) ile birleştirilir: api/certificate/:id/download → api.certificate.$id.download.ts.
• Literal nokta (örn. robots.txt) → [.] ile yazılır: robots[.]txt.ts.
• Index route → dosya adı _index.tsx (veya üst segment ile birlikte, örn. admin._index.tsx).
• API route’ları genelde .ts (React bileşeni yok); sayfa route’ları .tsx.

API vs Sayfa Route’ları

• api.*.ts: /api/* path’leri; loader ve/veya action export edilir; HTML sayfası döndürmez (JSON, redirect, dosya vb.).
• Sayfa route’ları (*.tsx): Default export bir React bileşeni; loader ile veri, action ile form işlemleri.

---

Layout Hiyerarşisi

Bazı route’lar layout görevi görür: ortak çerçeve (sidebar, header) sağlar ve alt route’ları <Outlet /> ile render eder. Hiyerarşi aşağıdaki gibidir.

Layout dosyası	Path	Sarmaladığı sayfalar
$lang.tsx	/:lang	Tüm dil prefix’li sayfalar: ana sayfa, pricing, teaching, login, register, instructor/, my-courses/, account/, learn/, cart, payment/checkout, courses/, course/:id, bundle/:slug, terms/, sitemap, messages, affiliate, onboarding, verify-email, forgot-password, reset-password, test-error, 404, 500.
admin.tsx	/admin	Admin alt sayfaları: /admin, /admin/courses, /admin/course/:slug/preview, /admin/users, /admin/finances, /admin/subscription, /admin/payouts, /admin/refunds, /admin/messages, /admin/price-tiers, /admin/kyc-requests, /admin/kyc/:userId/preview. Session + role admin kontrolü bu layout’ta yapılır.
instructor.tsx	/:lang/instructor	Eğitmen alt sayfaları: dashboard, create, payouts, messages, communication, performance/, course/:slug/manage/, bundles, bundles/:id/manage, coupons.
instructor.performance.tsx	/:lang/instructor/performance	Performance alt sayfaları: _index, students, reviews.
instructor.course.$slug.manage.tsx	/:lang/instructor/course/:slug/manage	Kurs yönetimi alt sayfaları: goals, course-structure, setup, filming, curriculum, captions, landing, pricing, promotions.
my-courses.tsx	/:lang/my-courses	Öğrenci “Kurslarım” alt sayfaları: _index (learn’e redirect), learn, wishlist, certifications, archived, tools.
account.tsx	/:lang/account	Hesap ayarları alt sayfaları: _index (profile’e redirect), profile, public-profile, password, subscription, purchase-history, payment-methods, notifications, settings.
$lang.terms.tsx	/:lang/terms	Yasal sayfalar: privacy-policy, terms-of-use, cookie-policy, instructor/*, refund.

Not: Dil prefix’i olmayan path’ler: /, /api/*, /admin/*, /verify/:code, /robots.txt, /sitemap.xml, /404, /500. Bunlar $lang.tsx layout’undan geçmez.

---

Ortak lib Modülleri

app/lib/ altındaki modüllerin kısa açıklamaları:

Modül	Açıklama
auth.ts	Better Auth yapılandırması: Drizzle adapter, Google OAuth, e-posta/şifre, e-posta doğrulama, şifre sıfırlama, databaseHooks (user create/update). initAuth(dbUrl, env, ctx?) ile handler alınır; Cloudflare Workers ortamında ctx.waitUntil ile auth e-postaları (doğrulama, şifre sıfırlama) arka planda tetiklenir.
auth-client.ts	Better Auth istemci tarafı; giriş/kayıt/çıkış ve session kullanımı için.
bunny.ts	Bunny CDN/Stream API fonksiyonları: altyazı yükleme (uploadCaption), silme (deleteCaption), listeleme (listCaptions). Video ve storage işlemleri.
bunny-video-status.ts	Bunny Stream video durumu: fetchBunnyVideoStatus, getBunnyVideoStatusKind (processing / ready / error).
can-message-instructor.ts	Öğrencinin eğitmene mesaj atıp atamayacağı kontrolü (enrollment vb.).
code-engine.ts	Kod alıştırması çalıştırma/değerlendirme (sandbox vb.).
coupon-engine.ts	Kupon doğrulama ve indirimli fiyat hesaplama: validateCoupon, calculateDiscountedPrice. Checkout ve sepet işlemlerinde kullanılır.
db-queries.ts	Tekrarlı veritabanı sorguları: kullanıcı, kurs, enrollment, admin istatistikleri, bildirim sayıları vb.
email.ts	E-posta gönderimi (Resend vb.); hoş geldin, doğrulama, şifre sıfırlama.
env.ts	Ortam değişkenleri erişimi; Cloudflare env ve yerel process.env; setEnv, getDbUrl vb.
exchange-rates.ts	Döviz kuru API ve çevrim: fetchExchangeRates, convertCurrency. KV cache ile optimize edilmiş kur çekme.
graphql-client.ts	Uygulama içi GraphQL istemcisi; /api/graphql endpoint’ine sorgu/mutation gönderir.
i18n.ts	i18next ve desteklenen diller; supportedLanguages, languageNames vb.
i18n-utils.ts	Path içinde dil değiştirme; getLangFromPath, changeLangInPath, shouldIncludeLang.
invoice-pdf.ts	Fatura PDF üretimi; /api/invoice/:enrollmentId/download tarafından kullanılır.
moderation.ts	İçerik moderasyonu ile ilgili yardımcılar.
notifications.ts	Bildirim sistemi: createNotification, getNotificationLangForUser. Kullanıcı dil tercihine göre bildirim oluşturma.
notification-messages.ts	Dil bazlı bildirim başlık ve mesaj şablonları. Tüm bildirim tipleri için çoklu dil desteği.
notification-ui-strings.ts	UI bildirim metinleri ve tarih locale fonksiyonları: getNotificationUIStrings, getDateLocale.
payout-engine.ts	Payout talebi mantığı; Connect vs manuel (TR) ayrımı.
pricing-engine.ts	Bölgesel fiyat hesaplama; Cloudflare request.cf (ülke) ile PPP/matrix; fiyat tier ve para birimi dönüşümü.
pricing.ts	Fiyat gösterimi ve tier ile ilgili yardımcı fonksiyonlar.
streak.ts	Öğrenme serisi (streak) ve günlük aktivite; getStreakData, getWeeklyActivity, recordLearningActivity, useStreakFreeze.
stripe-connect-payout.ts	Stripe Connect ödeme işleme; eğitmen payout transfer.
stripe-countries.ts	Stripe Connect destekli ülkeler listesi. Eğitmen onboarding’de ülke seçimi için kullanılır.
utils.ts	Genel yardımcı fonksiyonlar (format, sınıf birleştirme vb.).
video-security.ts	Bunny CDN imzalı video URL üretimi: generateSignedVideoUrl(videoId, libraryId, securityKey, expirationSeconds).

---

Özet

• app/routes/ — Sayfa ve API route’ları; path → dosya eşlemesi routes.ts’te; :param → $param, literal nokta → [.].
• app/components/ — Paylaşılan UI; alt klasörler domain’e göre (ui, instructor, learn, courses, pricing, teaching, messages).
• app/lib/ — Auth, DB, fiyat, GraphQL, video, e-posta, Stripe, streak, i18n, code-engine, bunny, coupon-engine, exchange-rates, notifications vb.
• app/db/ — Drizzle şema ve bağlantı.
• app/graphql/ — GraphQL şema (typeDefs + resolvers).
• app/locales/ — Dil dosyaları (tr, en, de, …).
• app/hooks/ — useLang, useLearningTracker, useChatNotifications vb.
• Layout’lar: $lang → tüm dil sayfaları; admin → admin alt sayfaları; instructor → eğitmen; my-courses → kurslarım; account → hesap ayarları.

Yeni bir sayfa eklerken önce app/routes.ts’e route tanımı ekleyin, sonra app/routes/ altında isimlendirme kuralına uygun dosyayı oluşturun. Ortak mantık için app/lib/ veya app/hooks/ kullanın.