README

A full-featured, modular Laravel starter kit powered by Laravel Chisel, Laravel Fortify, and Spatie Laravel Permission.

Designed for speed and cleanliness: choose your features during composer create-project, and Chisel automatically prunes unused backend routes, controllers, actions, Inertia pages, traits, model interfaces, and Pest tests.

⚡ Tech Stack

• Framework: Laravel 13 (PHP 8.5+)
• Frontend SPA: Inertia.js v3 + React 19
• TypeScript & Routing: Laravel Wayfinder (@/actions, @/routes)
• Styling: Tailwind CSS v4 + Radix UI primitives + Lucide Icons
• Bundler: Vite-Plus / Bun
• Authentication: Laravel Fortify
• Authorization / RBAC: Spatie Laravel Permission
• Feature Pruning: Laravel Chisel
• Testing: Pest 5

🚀 Quick Start

1. Create a New Project

composer create-project tooinfinity/infinity-starter-kit my-app

During setup, the post-create-project-cmd hook will automatically:

1. Generate your application encryption key.
2. Initialize your local database (database/database.sqlite).
3. Run database migrations.
4. Trigger the interactive php artisan install:features command powered by Chisel.

2. Select Your Features

When prompted:

Which authentication features would you like to enable?
 [x] Registration
 [x] Email verification
 [x] Two-factor authentication

Which authorization features would you like to enable?
 [x] Spatie Roles & Permissions (spatie/laravel-permission)

Select the features you want using Space, then press Enter.

3. Set Up Authorization (if enabled)

php artisan authorization:setup   # Creates permissions + Super Admin role
php artisan admin:setup           # Creates admin user interactively

4. Start Development

cd my-app
composer run dev

🛠️ Implemented Modules

🔐 Authentication Module

🛡️ Authorization & RBAC Module

A Policy-Free role-based access control system powered by spatie/laravel-permission, PHP string-backed enums, and Laravel Gates.

Architecture

Permission enum (source of truth)
        │
        ▼
Spatie Permission models
        │
Gate::before() ── Super Admin bypass
        │
Form Request authorize() ── Per-endpoint access control
        │
Inertia shared props ── Frontend authorization data
        │
useAuthorization() hook / <Can> component ── UI helpers

Key Design Decisions

• No Policies — All authorization uses Gate::before() for super-admin bypass, Spatie permission checks, and Form Request authorize() methods.
• PHP Enums — App\Enums\Permission and App\Enums\Role are the single source of truth for permission/role identifiers. No magic strings.
• Two Setup Commands — Separation of concerns: authorization:setup manages permissions/roles, admin:setup manages users.
• Frontend UI Helpers — useAuthorization() hook and <Can> component read shared Inertia props. These are UI helpers only; server-side authorization is the actual security boundary.

Permission Enum

enum Permission: string
{
    case UsersView = 'users.view';
    case UsersCreate = 'users.create';
    case UsersUpdate = 'users.update';
    case UsersDelete = 'users.delete';
}

Add your own permissions by extending the enum. Run php artisan authorization:setup to synchronize.

Role Enum

enum Role: string
{
    case SuperAdmin = 'super-admin';
}

Only super-admin is included in the starter kit. Add application-specific roles as needed.

Super Admin Bypass

Configured in AppServiceProvider via Gate::before():

Gate::before(function (User $user, string $ability): ?true {
    if ($user->hasRole(Role::SuperAdmin->value)) {
        return true;
    }
    return null;
});

Form Request Authorization

Use the Permission enum in Form Request authorize() methods:

public function authorize(): bool
{
    return $this->user()?->can(Permission::UsersCreate->value) ?? false;
}

Frontend Authorization

useAuthorization hook:

const { can, canAny, canAll, hasRole } = useAuthorization();

if (can('users.create')) { /* ... */ }
if (canAny(['users.update', 'users.delete'])) { /* ... */ }
if (hasRole('super-admin')) { /* ... */ }

Can component:

<Can permission="users.create">
    <Button>Create User</Button>
</Can>

<Can permissions={['users.update', 'users.delete']} mode="any">
    <Button>Manage Users</Button>
</Can>

Chisel Pruning

When authorization is disabled, Chisel removes:

• HasRoles trait from User model
• Gate::before() from AppServiceProvider
• Authorization shared props from HandleInertiaRequests
• config/permission.php and Spatie migrations
• app/Enums/Permission.php and app/Enums/Role.php
• Both setup commands
• Frontend hook, <Can> component, and authorization types
• All authorization tests

📊 Reporting & Analytics Module

A production-ready, read-only reporting engine designed to extract actionable insights directly from existing application models (users and audit_trails) without redundant tables or schema overhead.

Implemented Reports

Key Design Decisions

• Strictly Read-Only — Directly queries existing application tables; no parallel database models, snapshots, or migrations.
• Dedicated Query Services — Complex aggregations and filtering live in App\Queries\Reporting, keeping controllers clean and invokable.
• Spatie Data Transfer Objects — Typed contracts (ReportSummaryCardData, ReportTimeSeriesPointData, ReportBreakdownItemData, ReportMetadataData) serialize seamlessly to Inertia.
• Zero-Dependency Accessible Visualizations — Custom SVG/CSS charts featuring interactive tooltips, full keyboard/screen-reader accessibility, RTL layout support, and a companion tabular view switch.
• Secure Streaming CSV Export — Memory-efficient cursor streaming (cursor()), Excel UTF-8 BOM (\xEF\xBB\xBF), and formula injection sanitization (=, +, -, @, \t, \r neutralized).
• Granular RBAC Permissions — Protected via Permission::ReportsView (reports.view) and Permission::ReportsExport (reports.export).
• Trilingual Localization — Full translations available in English (en), French (fr), and Arabic (ar).

Chisel Pruning

When reporting is unselected in Chisel, all 25 reporting files (controllers, queries, DTOs, translations, frontend components, pages, and tests) are cleanly deleted and routes are removed.

🧩 Chisel-Based Scaffolding & Feature Installation

The Infinity Starter Kit features a deterministic, declarative feature configuration and pruning system built on Laravel Chisel (matching the architecture of official starter kits like laravel/react-starter-kit). The system operates strictly as a one-time project generation and scaffolding tool. Once configured via php artisan install:features, Chisel prunes all unselected features, cleans up its own installer files (chisel.php, InstallFeaturesCommand.php, and Chisel requirements), leaving behind pure, zero-overhead Laravel application code.

Feature Categories

• Core (Permanent): Authentication foundation (Laravel Fortify), base layout, Inertia v3 infrastructure, React 19 application shell, shared UI primitives (shadcn/ui), TypeScript configs, and SQLite database foundation. Core functionality is never pruned.
• Optional Modules:
  1. Authorization (authorization): Spatie Roles & Permissions, PHP enums, Gate super-admin bypass, frontend <Can> component and useAuthorization hook.
  2. Settings (settings): Key-value application settings storage, Setting model, settings controllers, forms, and pages.
  3. User Management (user-management): Administrative user directory, creation/edit modals, role assignment, user activation/deactivation.
  4. Localization (localization): Trilingual support (EN, FR, AR), RTL layout switching, Locale enum, LanguageSelector component, and @erag/lang-sync-inertia.
  5. Notifications (notifications): Database and email notification center, user preference toggles, notification dropdown and bell.
  6. Audit Trails (audit-trails): Searchable activity log tracking user actions, IP addresses, user agents, and timestamps.
  7. Reporting & Analytics (reporting): Read-only dashboards, SVG trend charts, date filtering, and streaming CSV exports.

🗺️ Feature Compatibility Matrix

📦 Installation Flow

During composer create-project, the post-create-project-cmd hook triggers php artisan install:features, prompting:

Which authentication features would you like to enable?
 [x] Registration
 [x] Email verification
 [x] Two-factor authentication

Which optional modules should be installed?
 [x] Authorization
 [x] Settings
 [x] User Management
 [x] Localization
 [x] Notifications
 [x] Audit Trails
 [x] Reporting

Non-Interactive Installation

Pass answers as a JSON string via the --answers option:

php artisan install:features --answers='{"auth_features":["registration","two-factor-authentication"],"optional_modules":["authorization","settings","user-management","localization","notifications","audit-trails","reporting"]}' --no-interaction

Unselected modules have all exclusive code, routes, permissions, translations, and dependencies cleanly pruned.

Post-Installation Self-Cleanup

Upon finishing execution, Chisel automatically cleans up the repository:

1. Strips @php artisan install:features --ansi and "laravel/chisel" from composer.json.
2. Formats all PHP code using Laravel Pint (vendor/bin/pint --format agent).
3. Re-generates Wayfinder typed routes and actions (php artisan wayfinder:generate --with-form --no-interaction).
4. Deletes chisel.php, app/Console/Commands/InstallFeaturesCommand.php, and Chisel installer tests.

➕ Developer Checklist: Adding a New Scaffolding Feature

Adding a new optional module or feature in chisel.php is simple and declarative:

1. Add Question Option: Add the feature identifier and label to the optional_modules question in chisel.php.
2. Register Selected Handler: Use ->selected('optional_modules', '<feature>', then: fn(Chisel $c) => ..., else: fn(Chisel $c) => ...):
   • In then: use $c->files(...)->removeSectionMarkers('<tag>') to strip markers when kept.
   • In else:
     • AST mutations via $c->php('...')->removeImport(...)->removeTrait(...)
     • Strip sections via $c->files(...)->removeSection('<tag>')
     • Delete exclusive files via $c->files(...)->delete()
     • Prune exclusive packages via $c->file('composer.json')->removeLinesContaining(...)
     • Prune empty directories using chiselPruneEmptyDirectories(__DIR__, [...])
3. Handle Shared Packages: Use ->selectedAny('optional_modules', ['<feature1>', '<feature2>'], else: ...) for packages shared across multiple features.
4. Wrap Shared Code in Markers: Surround feature-specific routes, sidebar items, and type definitions with /* @chisel-<tag> */ and /* @end-chisel-<tag> */.
5. Verify with Pint & Pest: Run vendor/bin/pint --format agent and php artisan test.

🧪 Testing & Quality Control

# Run full test suite with 100% code coverage requirement
composer test

# Run all unit and feature tests
vendor/bin/pest tests/Unit tests/Feature --compact

# Check type coverage (100% required)
vendor/bin/pest --type-coverage --min=100

# Static analysis (PHPStan at max level)
vendor/bin/phpstan analyse

# Code formatting & styling
composer run lint

📁 Key Directory Structure

├── app/
│   ├── Actions/                  # Reusable business logic actions
│   ├── Console/Commands/         # Artisan commands
│   │   ├── InstallFeaturesCommand.php
│   │   ├── SetupAuthorizationCommand.php
│   │   └── SetupAdminUserCommand.php
│   ├── Data/                     # Spatie Data transfer objects
│   │   └── Reporting/            # Report summary, series, and breakdown DTOs
│   ├── Enums/                    # PHP string-backed enums
│   │   ├── AuditEvent.php
│   │   ├── Permission.php
│   │   ├── ReportCategory.php
│   │   ├── ReportType.php
│   │   └── Role.php
│   ├── Http/
│   │   ├── Controllers/          # Inertia HTTP controllers
│   │   │   ├── AuditTrails/
│   │   │   ├── Reporting/        # Invokable reporting & export controllers
│   │   │   └── Users/
│   │   ├── Middleware/           # HandleInertiaRequests (shares auth data)
│   │   └── Requests/            # Form Requests with authorize() & validation
│   ├── Models/                   # Eloquent models (User, AuditTrail, Setting)
│   ├── Queries/                  # Read-only query & export services
│   │   ├── AuditTrails/
│   │   ├── Reporting/            # UserReportQuery, AuditReportQuery, CSV streams
│   │   └── Users/
│   └── Providers/                # AppServiceProvider (Gate::before)
├── chisel.php                    # Feature pruning configuration
├── config/
│   ├── fortify.php
│   └── permission.php            # Spatie Permission config
├── database/migrations/          # Users, Audit Trails, Settings, Permissions
├── lang/                         # Localized translations (en, fr, ar)
├── resources/js/
│   ├── components/
│   │   ├── can.tsx               # <Can> authorization component
│   │   └── reports/              # Summary cards, SVG charts, date range filters
│   ├── hooks/
│   │   └── use-authorization.ts  # useAuthorization() hook
│   ├── pages/
│   │   └── reports/              # Catalog index, Users report, Audit report
│   └── types/
│       ├── auth.ts               # Auth type with permissions/roles
│       └── reports.ts            # Report DTO & filter type definitions
└── tests/
    ├── Feature/
    │   ├── Authorization/        # RBAC + command tests
    │   └── Reporting/            # Report queries, controllers, exports, and pruning tests
    └── Unit/
        ├── Enums/                # Enum tests
        └── Reporting/            # Report type & category tests

📄 License

This starter kit is open-sourced software licensed under the MIT license.