README

An opinionated Laravel starter kit built on PostgreSQL schemas, Inertia v3 + React 19, and an action-based architecture. Designed for developers who want clear domain boundaries, type safety across the full stack, and sensible defaults from day one.

Stack

Getting Started

Requires PHP 8.2+, PostgreSQL, Node.js, and pnpm.

Create your app using Laravel installer:

laravel new my-app --using=esfredderick/rilt-psql-blank-starter-kit

Initial setup

cd example-app

# runs migrations using your own db credentials
composer setup

# runs the dev server
composer dev

Architecture Overview

Important

This section describes the conventions and patterns embedded in this starter kit — not automatic behaviors. They define how the codebase is structured and how new features should be built. Detailed guidelines live in .ai/guidelines/project-architecture.md.

PostgreSQL Schemas as Domain Boundaries

Tables live in named schemas instead of the default public schema. Treat each schema as a domain boundary and keep schema, table, and folder examples placeholder-based so each application can choose its own domain names. Schemas are created via dedicated migrations, and models declare their table with schema-qualified names:

protected $table = '{domain}.{table}';

The esfredderick/useful-artisan-commands package automatically creates the database and migration schema when they don't exist during migration commands - no application service provider setup required while Laravel package discovery is enabled. When Laravel framework table defaults need to move into named schemas, run php artisan schemas:config-defaults from the same package to schema-qualify the relevant configuration defaults.

Domain-Driven Directory Structure

Database schemas and table concerns mirror into PHP namespaces and frontend directories. Models stay directly under the domain namespace, and route files are grouped by domain:

app/
  Actions/{Domain}/{Subdomain}/
  Data/{Domain}/{Subdomain}/
  Exceptions/{Domain}/{Subdomain}/
  Http/Controllers/{Domain}/{Subdomain}/
  Http/Requests/{Domain}/{Subdomain}/
  Models/{Domain}/
resources/js/
  components/domain/{domain}/{subdomain}/
  pages/{domain}/{subdomain}/
routes/
  domain/{domain}.php
tests/
  Feature/{Domain}/

Action-Based Business Logic

All business logic goes into Action classes — controllers stay thin. Artisan commands for generating both are provided by esfredderick/useful-artisan-commands:

php artisan make:action {Domain}/{Subdomain}/{ActionName}    # -> app/Actions/{Domain}/{Subdomain}/{ActionName}Action.php (-d to also create DTO)
php artisan make:data {Domain}/{Subdomain}/{DataName}        # -> app/Data/{Domain}/{Subdomain}/{DataName}Data.php

Actions are plain classes with a handle() method. DTOs are final readonly classes used when actions need three or more input values.

Thin Controllers

Controllers follow a strict injection order and flow:

FormRequest → Route params → Action (via method DI)

Form Requests handle validation and expose a getData() method that transforms input into a DTO. The controller calls $action->handle($request->getData()), flashes feedback via Inertia::notify(), and redirects.

Exception Handling

AppException is the base exception class. Domain-specific exceptions extend it and auto-render as flash messages — no try-catch needed:

throw new InsufficientBalanceException(); // flashes + redirects back automatically

Frontend Feedback System

Two flash channels from backend to frontend:

• Callout — persistent inline alert via <ResponseCallout />
• Transient — auto-dismissing Sonner toast via useTransientListener()

Both are triggered through a single macro:

Inertia::notify('Done!', ResponseStyle::TRANSIENT);
Inertia::notify('Check this.', ResponseStyle::CALLOUT, EmphasisVariant::INFORMATIVE);

Emphasis Variant System

A semantic color/icon system spanning the full stack:

• Backend: EmphasisVariant enum (AFFIRMATIVE, INFORMATIVE, PREVENTIVE, DESTRUCTIVE, INTERROGATIVE, NEUTRAL)
• Type Bridge: Wayfinder auto-generates TypeScript constants and types
• CSS: Custom oklch() color tokens per variant (light + dark)
• Components: shadcn Alert extended with variant classes, useDecorator() hook for icon resolution

Wayfinder Type Bridge

Laravel Wayfinder (dev-next) generates typed TypeScript from Laravel routes, models, enums, form requests, and Inertia page props. All output lives under resources/js/wayfinder/ and auto-regenerates via Vite plugin during development.

Inertia shared props and flash data are typed through module augmentation in resources/js/types/global.d.ts.

Frontend Conventions

• UI primitives from shadcn/ui live in components/ui/
• Custom reusable components live in components/ux/ using composition pattern
• Decoration records map enum variants to UI properties via Pick<Decoration, ...> — see decorations/ui/emphasis-decoration.ts
• Theme managed by useAppearance() hook (light/dark/system, cookie-persisted for SSR)

Custom Available Commands

Commands provided by esfredderick/useful-artisan-commands (dev dependency):

Code Quality

All standard php artisan make:* commands (model, controller, request, migration, etc.) are available as usual.

Application Defaults

Configured in AppServiceProvider:

• CarbonImmutable as default date class
• Strict model mode outside production
• Destructive DB commands prohibited in production
• Aggressive Vite prefetching
• HTTPS forced in production
• Password rules enforced in production (min 12, mixed case, symbols, uncompromised)

License

MIT