Proje Dokumantasyonu

Bu proje; Laravel 12, Inertia.js v2, Vue 3, SSR, Passport API authentication ve paket destekli bir UI toolkit uzerine kurulu admin-oncelikli bir starter uygulamadir.

Backend mimarisi

Kod tabani, tum is mantigini controller icine koymak yerine domain odakli bir yapi kullanir.

Ana domain modulleri

• app/Domain/Auth
• app/Domain/User
• app/Domain/Role
• app/Domain/Setting
• app/Domain/Session
• app/Domain/Media
• app/Domain/ActivityLog
• app/Domain/ApiRoute
• app/Domain/Shared

Tipik request akisi

1. Route, ince tutulmus bir controller'a gider.
2. Gerekliyse validasyon Form Request ile yapilir.
3. Veri, ilgili ozellik DTO kullaniyorsa DTO'ya donusturulur.
4. Is mantigi app/Domain/.../Actions altindaki action siniflarinda calisir.
5. Listeleme ve filtreleme icin Query siniflari kullanilir.
6. Cevaplar Inertia veya to_api() ile donulur.

Domain event'leri

app/Providers/DomainServiceProvider.php su eslesmeleri kaydeder:

• UserCreated -> LogUserCreated
• UserUpdated -> LogUserUpdated
• RoleCreated -> LogRoleCreated

Bu sayede yan etkiler ana action siniflarinin disinda kalir.

Routing ve yetkilendirme

Web route'lari

routes/web.php, routes/web/ altindaki route dosyalarini yukler.

• public route'lar once yuklenir
• authenticated route'lar auth ve verified altinda gruplanir
• permission korumali route dosyalari check.permission ile sarilir

API route'lari

routes/api.php, routes/api/ altindaki dosyalari /api/v1 altinda yukler.

• public endpoint'ler token auth istemez
• authenticated endpoint'ler auth:api kullanir
• korumali endpoint'ler ek olarak check.permission kullanabilir

Permission cozumleme

check.permission middleware'i route isimlerinden yetki adini otomatik cikarir.

Ornekler:

• users.index -> users.read
• users.store -> users.create
• settings.update.general -> settings.update route icinde acik verildiginde

Ilgili rehber:

• Roller ve Yetkiler Rehberi

Frontend mimarisi

Inertia sayfalari

Sayfalar resources/js/pages/ altinda bulunur.

Ornekler:

• resources/js/pages/Admin/Users
• resources/js/pages/Admin/Roles
• resources/js/pages/Admin/Settings
• resources/js/pages/Profile

Local composable'lar

Projeye ozel composable'lar resources/js/composables/ altinda tutulur.

Ilgili rehber:

• Composable Rehberi

Paket destekli UI toolkit

Admin panel, local pakete baglanan @lvntr/* alias'i uzerinden gelen UI bloklarini kullanir.

Ornekler:

• @lvntr/components/DatatableBuilder/core
• @lvntr/components/FormBuilder/core
• @lvntr/components/TabBuilder/core
• @lvntr/components/ui/AppDialog.vue

Ilgili rehberler:

• DataTable Rehberi
• FormBuilder Rehberi
• Tabs Rehberi
• UI Bilesenleri Rehberi

Ortak frontend kaliplari

AdminLayout icindeki global overlay'ler

AdminLayout.vue, ortak overlay bilesenlerini bir kez render eder:

• ConfirmDialogComponent
• ToastComponent
• AppDialog

Definitions ve enum'lar

• PHP enum verileri Inertia ile paylasilir ve useEnum() ile kullanilir
• veritabani tabanli definitions verileri /definitions endpoint'inden useDefinition() ile alinir

Flash mesajlari

Controller'lar flash mesajlarla redirect eder, AdminLayout.vue ise bunlari PrimeVue toast olarak gosterir.

Project Documentation

This project is a Laravel 12 admin-first starter application with Inertia.js v2, Vue 3, SSR, Passport API authentication, and a package-backed UI toolkit.

Backend architecture

The codebase uses a domain-oriented structure instead of placing all business logic directly inside controllers.

Main domain modules

• app/Domain/Auth
• app/Domain/User
• app/Domain/Role
• app/Domain/Setting
• app/Domain/Session
• app/Domain/Media
• app/Domain/ActivityLog
• app/Domain/ApiRoute
• app/Domain/Shared

Typical request flow

1. Route resolves to a thin controller.
2. Validation is handled by a Form Request when needed.
3. Payload is mapped into a DTO where the feature uses DTOs.
4. Business logic lives in Action classes under app/Domain/.../Actions.
5. Query classes prepare listing and filter data when needed.
6. Responses are returned through Inertia or to_api().

Domain events

app/Providers/DomainServiceProvider.php registers event-listener pairs such as:

• UserCreated -> LogUserCreated
• UserUpdated -> LogUserUpdated
• RoleCreated -> LogRoleCreated

This keeps side effects outside the main action classes.

Routing and permissions

Web routes

routes/web.php loads route files from routes/web/.

• public routes are loaded first
• authenticated routes are grouped under auth and verified
• permission-protected route files are wrapped with check.permission

API routes

routes/api.php loads files from routes/api/ under /api/v1.

• public endpoints are available without token auth
• authenticated endpoints use auth:api
• protected endpoints can also use check.permission

Permission resolution

The check.permission middleware maps route names to permissions automatically.

Examples:

• users.index -> users.read
• users.store -> users.create
• settings.update.general -> settings.update when applied explicitly in routes

Related guide:

• Roles & Permissions System Guide

Frontend architecture

Inertia pages

Pages live under resources/js/pages/.

Examples:

• resources/js/pages/Admin/Users
• resources/js/pages/Admin/Roles
• resources/js/pages/Admin/Settings
• resources/js/pages/Profile

Local composables

Project-specific composables live under resources/js/composables/.

Related guide:

• Composables Guide

Package-backed UI toolkit

The admin panel uses UI building blocks exposed through the @lvntr/* alias, which points to the local package resources.

Examples:

• @lvntr/components/DatatableBuilder/core
• @lvntr/components/FormBuilder/core
• @lvntr/components/TabBuilder/core
• @lvntr/components/ui/AppDialog.vue

Related guides:

• DataTable Component Guide
• FormBuilder Component Guide
• Tabs Component Guide
• UI Components Guide

Shared frontend patterns

Global overlays in AdminLayout

AdminLayout.vue renders the shared overlays once:

• ConfirmDialogComponent
• ToastComponent
• AppDialog

Definitions and enums

• PHP enums are shared through Inertia and consumed with useEnum()
• database-backed definitions are loaded from /definitions with useDefinition()

Flash messages

Controllers redirect with flash messages, and AdminLayout.vue turns them into PrimeVue toasts.