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 <Module> çalıştırın — Modül Sahipliği tablosu için README'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\<Module>\... import'ları class_alias ile çalışmaya devam eder; eject ya da eski kurulumdan kalan yerel app/Domain/<Module>/ 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 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 <Tag> 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ıç

Backend & DDD

Frontend & UI builder'lar

Özellikler

Araçlar