# Proje Dökümantasyonu Bu döküman, kurulumdan sonra starter kit'in yüksek seviyeli haritasını verir. Laravel 13, Inertia.js v3, Vue 3.5, Passport API authentication, Fortify web auth akışları ve paket destekli bir UI toolkit üzerine kurulu admin-öncelikli bir starter uygulamasıdır. ## Backend Alanları - uygulamanıza scaffold edilen iş mantığı için `app/Domain/`; vendor-managed domain'lerin runtime katmanı paket içinde `src/Domain/` (`Lvntr\StarterKit\Domain\`) altında yaşar - web ve API giriş noktaları için `app/Http/Controllers/` - API yanıt biçimlendirmesi için `app/Http/Responses/` - Eloquent modelleri için `app/Models/` - app, domain, settings ve Fortify bootstrapping için `app/Providers/` - modüler route yükleme için `routes/web*` ve `routes/api*` ### Ana Domain Modülleri **Yüzey sahipliği modül bazında ayrılır** — Model'ler her zaman app-owned kalır; yüzeyin geri kalanı modüle bağlıdır. Domain runtime ve HTTP/Vue yüzeyi modüle göre ayrılır: - `Auth` tamamen app tarafındadır (`app/Domain/Auth`) - `User` ve `Role` uygulamaya scaffold edilir (controller, FormRequest, Vue) ama `app/Domain/...` altında yalnızca app-owned `BulkActions` dilimini tutar; ana domain runtime vendor-resident'tır - `Setting`, `ApiRoute`, `Logs`, `ActivityLog` ve `Files` **vendor-first**'tür: controller, FormRequest ve Vue sayfalarının tümü paketten çalışır (yalnızca Model'leri `app/`'te kalır). Uygulamaya çekmek için `sk:eject ` çalıştırın — Modül Sahipliği tablosu için [README](../README.md)'ye bakın **Vendor-resident runtime domain'leri (`src/Domain/`, `Lvntr\StarterKit\Domain\`)** — bu modüllerin Actions, DTOs, Queries, Events, Listeners ve Services katmanları paket içinden çalışır ve temiz kurulumda uygulamanıza kopyalanmaz. `App\Domain\\...` import'ları `class_alias` ile çalışmaya devam eder; eject ya da eski kurulumdan kalan yerel `app/Domain//` kopyası varsa önceliklidir: - `ActivityLog` - `ApiClient` - `ApiRoute` - `FileManager` - `Logs` - `Media` - `Role` - `Session` - `Setting` - `Shared` - `User` Tam vendor-resident model ve reconcile adımları için [ddd.md](https://starter-kit.lvntr.dev/tr/docs/ddd) dosyasına bakın. ### Tipik Request Akışı 1. Route, ince tutulmuş bir controller'a gider. 2. Gerekliyse validasyon Form Request ile yapılır. 3. Veri, ilgili özellik DTO kullanıyorsa DTO'ya dönüştürülür. 4. İş mantığı action sınıflarında çalışır — scaffold edilen domain'ler için `app/Domain/.../Actions`, vendor-resident olanlar için `src/Domain/.../Actions` (vendor namespace) altında. 5. Listeleme ve filtreleme için Query sınıfları kullanılır. 6. Cevaplar Inertia veya `to_api()` ile döndürülür. ### Domain Event'leri Vendor-resident `User`, `Role` ve `Logs` runtime'ına ait kit audit event/listener eşleşmeleri vendor FQCN'leriyle `StarterKitServiceProvider::registerEventListeners()` içinde kaydedilir: - `UserCreated -> LogUserCreated` - `UserUpdated -> LogUserUpdated` - `UserDeleted -> LogUserDeleted` - `RoleCreated -> LogRoleCreated` - `RoleUpdated -> LogRoleUpdated` - `RoleDeleted -> LogRoleDeleted` - `LogFilesDeleted -> LogActivityForLogFilesDeleted` Scaffold edilen `app/Providers/DomainServiceProvider.php` kendi uygulama event'leriniz için bırakılır. `sk:eject`, bir kit domain'ini tekrar `app/Domain/` altına kopyaladığınızda buraya binding ekleyebilir. ## Frontend Alanları - Inertia sayfaları için `resources/js/pages/` - ortak layout'lar için `resources/js/layouts/` - tekrar kullanılabilir starter-kit bileşenleri için `resources/js/components/Lvntr-Starter-Kit/` - istemci tarafı davranışları için `resources/js/composables/` - Wayfinder tarafından üretilen yardımcılar için `resources/js/routes/` ve `resources/js/actions/` ### Inertia Sayfaları Sayfalar `resources/js/pages/` altında bulunur. Örnekler: - `resources/js/pages/Admin/Users` - `resources/js/pages/Admin/Roles` - `resources/js/pages/Admin/Settings` - `resources/js/pages/Admin/ApiRoutes` - `resources/js/pages/Admin/Files` - `resources/js/pages/Admin/Logs` - `resources/js/pages/Profile` ### Tekrar Kullanılabilir UI Toolkit Admin panel, `@lvntr/*` alias'ı üzerinden gelen ortak UI bloklarını kullanır. Örnekler: - `@lvntr/components/DatatableBuilder/core` - `@lvntr/components/FormBuilder/core` - `@lvntr/components/TabBuilder/core` - `@lvntr/components/ui/AppDialog.vue` ## Request Desenleri - tarayıcı sayfaları Inertia kullanır - JSON endpoint'leri `to_api()` ve `ApiResponse` kullanır - liste yoğun admin ekranları datatable query sınıflarını kullanır - settings ve benzeri yazma işlemleri Form Request ve Action üzerinden akmalıdır ### Authentication Çalışma Yapısı - Fortify, tarayıcı auth ekranlarını `resources/js/pages/Auth` altındaki Inertia sayfaları üzerinden render eder - login pipeline'ı rate limiting, Turnstile doğrulaması, pasif kullanıcı engeli ve opsiyonel iki faktör yönlendirmesini içerir - Passport, API tüketicileri için `/api/v1/auth/*` personal access token akışlarını yönetir ## Routing Stratejisi Route dosyaları özelliğe göre bölünür. `routes/web.php`, `routes/web/` altındaki dosyaları yükler; `routes/api.php` ise `routes/api/` altındaki dosyaları yükler. - public route'lar önce yüklenir - authenticated route'lar `auth` ve `verified` altında gruplanır - permission korumalı route dosyaları `check.permission` ile sarılır - API route'ları `/api/v1` altında throttle ve `auth:api` kurallarıyla gruplanır ### Frontend Servis Route'ları `routes/web/service-route.php`, giriş yapmış web kullanıcıları için yüklenir: - `GET /definitions`, `useDefinition()` ve builder tabanlı option yüklemelerini besler - `GET /roles/options`, admin form ve filtreleri için select seçenekleri sağlar ### Public Yardımcı Route'lar `routes/web/public-route.php`, herkese açık hafif yardımcı route'ları taşır: - `POST /locale`, aktif arayüz dilini session içinde günceller ### Özellik Bazlı Admin Route'ları Bazı admin ekranları kendi route dosyalarında ayrılmıştır: - `routes/web/developer-route.php`, `api-routes.*` ekranını yükler - `routes/web/files-route.php`, global dosya yöneticisini `files.index` adıyla açar - `routes/web/log-route.php`, system-admin log görüntüleyiciyi `logs.*` altında açar - `routes/web/profile-route.php`, profil, avatar ve tarayıcı oturumları uçlarını içerir ## Ortak Yapı Taşları - `app/Helpers/sk-helpers.php` ve `app/Helpers/custom.php` içindeki helper'lar - `ApiException` ve `ApiExceptionHandler` - permission middleware (`check.permission`) - security headers middleware - definitions sistemi ### `AdminLayout` İçindeki Global Overlay'ler `AdminLayout.vue`, ortak overlay bileşenlerini bir kez render eder: - `ConfirmDialogComponent` - `ToastComponent` - `AppDialog` - `ImageLightbox` ### Definitions Mevcut UI akışı, ayrı bir enum paylaşım katmanından ziyade veritabanı tabanlı definitions sistemini merkezde tutar. - `_02_DefinitionSeeder.php`, `userStatus`, `gender`, `identityType` ve `yesNo` gibi key'leri seed eder - `DefinitionService` (vendor-resident `Lvntr\StarterKit\Domain\Shared\Services\`, `App\Domain\Shared\Services\DefinitionService` alias'ı üzerinden erişilebilir) definition kayıtlarını locale bazlı gruplayıp cache'ler - `useDefinition()`, bunları `GET /definitions` üzerinden tüketir - definition kayıtları label, severity ve opsiyonel icon metadatası taşır - `SkDatatable` ve `SkForm`, `.tag('definition').tagKey('userStatus')` ve `.definitionOptions('gender')` gibi tanımlarla bu key'lere doğrudan bağlanabilir - `SkDatatable`, definition tag'lerini PrimeVue `` ile render eder; böylece DB tabanlı metadata kolon seviyesindeki `colors()`, `icons()` ve tag stil yardımcıları ile birleştirilebilir ### Flash Mesajları Controller'lar flash mesajlarla redirect eder, `AdminLayout.vue` ise bunları PrimeVue toast olarak gösterir. ### Local Composable'lar Projeye özel composable'lar `resources/js/composables/` altında tutulur. Admin sidebar tarafında menü tanımları `useAdminMenu()` içinde kalır; filtreleme ve aktif durum mantığı ise ortak `useMenuBuilder()` composable'ı ile paylaşılır. ## Önerilen Okuma **Başlangıç** - [welcome.tr.md](https://starter-kit.lvntr.dev/tr/docs/welcome) — kit nedir ve içinde ne gelir - [project-info.tr.md](https://starter-kit.lvntr.dev/tr/docs/introduction) — stack ve yüksek seviyeli proje özeti - [install.tr.md](https://starter-kit.lvntr.dev/tr/docs/install) — kurulum akışı - [update.tr.md](https://starter-kit.lvntr.dev/tr/docs/update) — güncel stub'ları çekme (hash tabanlı) - [UPGRADE.tr.md](https://starter-kit.lvntr.dev/tr/docs/upgrade) — sürüm yükseltme notları **Backend & DDD** - [ddd.tr.md](https://starter-kit.lvntr.dev/tr/docs/ddd) — domain yerleşimi ve vendor-resident model - [auth.tr.md](https://starter-kit.lvntr.dev/tr/docs/auth) — Fortify (web) + Passport (API) kimlik doğrulama - [roles-permissions.tr.md](https://starter-kit.lvntr.dev/tr/docs/roles-permissions) — permission resource'ları ve seed - [api.tr.md](https://starter-kit.lvntr.dev/tr/docs/api) — API yanıt zarfı ve konvansiyonlar - [api-clients.tr.md](https://starter-kit.lvntr.dev/tr/docs/api-clients) — Passport client & token yönetimi - [api-routes.tr.md](https://starter-kit.lvntr.dev/tr/docs/api-routes) — API route envanteri ekranı - [module-routes.tr.md](https://starter-kit.lvntr.dev/tr/docs/module-routes) — modüler route registry - [definitions.tr.md](https://starter-kit.lvntr.dev/tr/docs/definitions) — ortak label/value lookup'ları - [settings.tr.md](https://starter-kit.lvntr.dev/tr/docs/settings) — uygulama ayarları modülü - [activity-logs.tr.md](https://starter-kit.lvntr.dev/tr/docs/activity-logs) — audit/aktivite loglama - [logs.tr.md](https://starter-kit.lvntr.dev/tr/docs/logs) — uygulama log görüntüleyici **Frontend & UI builder'lar** - [formbuilder.tr.md](https://starter-kit.lvntr.dev/tr/docs/formbuilder) — FormBuilder (FB) - [datatable.tr.md](https://starter-kit.lvntr.dev/tr/docs/datatable) — DatatableBuilder (DB) - [tabs.tr.md](https://starter-kit.lvntr.dev/tr/docs/tabs) — TabBuilder (TB) - [composables.tr.md](https://starter-kit.lvntr.dev/tr/docs/composables) — Vue composable'ları - [admin-components.tr.md](https://starter-kit.lvntr.dev/tr/docs/admin-components) — admin sayfa stil rehberi - [ui-components.tr.md](https://starter-kit.lvntr.dev/tr/docs/ui-components) — tekrar kullanılabilir UI primitive'leri - [theme.tr.md](https://starter-kit.lvntr.dev/tr/docs/theme) — tema sistemi - [wayfinder.tr.md](https://starter-kit.lvntr.dev/tr/docs/wayfinder) — tip güvenli route helper'ları **Özellikler** - [file-manager.tr.md](https://starter-kit.lvntr.dev/tr/docs/file-manager) — dosya yöneticisi - [files.tr.md](https://starter-kit.lvntr.dev/tr/docs/files) — dosya yükleme - [i18n.tr.md](https://starter-kit.lvntr.dev/tr/docs/i18n) — uluslararasılaştırma - [translatable-fields.tr.md](https://starter-kit.lvntr.dev/tr/docs/translatable-fields) — çok dilli model alanları **Araçlar** - [artisan-commands.tr.md](https://starter-kit.lvntr.dev/tr/docs/artisan-commands) — `sk:*` komut referansı - [claude-skills.tr.md](https://starter-kit.lvntr.dev/tr/docs/claude-skills) — paketle gelen Claude Code skill'leri