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

📋 Supported Runtime & Toolchain Versions

Component	Supported Version / Constraint	Notes
PHP	`^8.5.0` (8.5+)	Required extensions: `pdo`, `pdo_sqlite`, `pdo_mysql`, `pdo_pgsql`, `pcov`, `mbstring`, `openssl`, `tokenizer`, `xml`
Composer	`v2.x`	Strictly reproducible installs with `composer.lock`
Bun	`^1.2` / `^1.3` (1.2+)	Fast package manager, scripts, and runtime
Node.js	`>= 24.x`	Used by Vite+ toolchain and Playwright
Laravel	`^13.32.0` (Laravel 13)	Core application framework
Inertia.js	`^3.0.6` (Laravel) / `^3.7.1` (React)	Full-stack SPA bridge
React	`^19.3.0` (React 19)	Frontend UI library
TypeScript	`^7.0.2`	Typed frontend codebase and Wayfinder routes
Tailwind CSS	`^4.3.3` (Tailwind 4)	CSS compiler & styling
Database Engines	SQLite 3.35+, MySQL 8.0+, PostgreSQL 16+	Tested continuously across all 3 engines

🚀 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:

Generate your application encryption key.
Initialize your local database (database/database.sqlite).
Run database migrations.
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 optional modules should be installed?
 [x] Authorization
 [x] Settings
 [x] User Management
 [x] Localization
 [x] Notifications
 [x] Audit Trails
 [x] Reporting

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

Dry-Run Mode (Preview Planned Mutations)

To inspect all planned operations without applying any changes to your files, packages, or database, pass the --dry-run flag:

# Preview interactive feature selection
php artisan install:features --dry-run

# Preview automated/CI selections via JSON answers
php artisan install:features --dry-run --answers='{"auth_features":["registration"],"optional_modules":["authorization","user-management"]}'

Dry-run mode:

Resolves explicitly selected features and identifies dependency-derived requirements (e.g. login required by registration).
Enforces identical validation semantics as real installations (failing on invalid or missing dependencies).
Displays a structured preview of pruned files and directories, package removals, database operations, tooling steps, and installer cleanup.
Guarantees zero mutations to the filesystem, dependencies, database, or git status.

3. Authorization & Super Admin (if enabled)

During interactive installation, authorization permissions and an administrator account are configured automatically. If you installed non-interactively, need to bootstrap a fresh production database, or updated the Permission or Role enums:

php artisan authorization:setup   # Synchronizes permissions + Super Admin role

Note: Always run php artisan authorization:setup before assigning the super-admin role so that the role and permissions exist in the database.

To create the initial Super Admin interactively (with hidden password prompts and confirmation):

php artisan authorization:create-admin

Or pass --email and --name, piping the password via STDIN for non-interactive deployment automation:

echo "your-secure-password" | php artisan authorization:create-admin --name="Administrator" --email="admin@example.com" --no-interaction

To promote an existing registered user to Super Admin:

php artisan authorization:create-admin --email="admin@example.com"

4. Start Development

cd my-app
composer run dev

🛠️ Implemented Modules

🔐 Authentication Module

Feature	Description	Chisel Pruning
Registration	User registration form, routes, and user creation action.	Removes `/register` route, registration page, and login page register links.
Email Verification	Native Fortify verification flow (`MustVerifyEmail`), verification notice page, resend notifications.	Strips `MustVerifyEmail` interface, removes verification controllers, views, and tests.
Two-Factor Authentication	TOTP / QR codes, recovery codes, security settings page, and 2FA challenge flow.	Strips `TwoFactorAuthenticatable` trait, removes 2FA routes, settings UI, controllers, and tests.
Account & Security	Login/logout, password reset, profile updates, password change, appearance settings.	Core — always retained.

🛡️ 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.
Dedicated Setup Commands — authorization:setup synchronizes permissions and roles from PHP enums to the database. Initial Super Admin provisioning is handled during installation or via the runtime authorization:create-admin command.
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

Report	Path	Metrics & Visualizations
User Activity & Growth	`/reports/users`	Total users, active/inactive counts, period registrations, daily registration trend SVG chart, and filterable/sortable user listing.
Audit Trail Activity	`/reports/audit`	Total audit events, active actors, top event & resource, event distribution breakdown, daily volume trend chart, and audit log table.

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 chunked streaming (lazy()), 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. Settings (such as application name and display timezone) are dynamically applied per web request via HandleSettings middleware using a cached payload (settings.all); CLI commands and queued background workers rely on base environment configuration (.env / config/app.php).
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, with automated retention pruning and transactional PII anonymization on account deletion.
7. Reporting & Analytics (reporting): Read-only dashboards, SVG trend charts, date filtering, and streaming CSV exports.

🗺️ Feature Compatibility Matrix

Module	Identifier	Description	Required Dependencies	Optional Dependencies	Composer Packages	Frontend Packages (Bun)	Permissions	Default	Capabilities
Authorization	`authorization`	Policy-free role-based access control powered by Spatie Permission, PHP enums, and super-admin gate bypass.	—	—	`spatie/laravel-permission`	—	`authorization.manage`	Enabled	Role & permission management, Super-admin gate bypass, Inertia shared auth props, component & useAuthorization hook
Settings	`settings`	Key-value application settings storage with per-request caching and dynamic runtime configuration.	`authorization`	—	—	—	`settings.manage`	Enabled	Key-value settings storage, Cached per-request runtime resolution, Application name & timezone configuration, Settings management UI
User Management	`user-management`	Administrative user directory with user creation, profile editing, role assignment, and lifecycle controls.	`authorization`	—	—	—	`users.view`, `users.create`, `users.update`, `users.delete`, `users.manage-roles`, `users.manage-password`	Enabled	User directory listing & filtering, User creation & editing, Role assignment & self-protection, Account activation & deactivation, Password management
Localization	`localization`	Trilingual localization with real-time language switching, RTL layout support, and Inertia translation sync.	—	—	`erag/laravel-lang-sync-inertia`	`@erag/lang-sync-inertia`	—	Enabled	Trilingual support (EN, FR, AR), RTL layout auto-switching, Language selector component, Persistent guest & user locale cookie, Inertia translation synchronization
Notifications	`notifications`	Database and email notification system with user channel preferences and interactive notification center.	—	—	—	—	—	Enabled	Database & email notifications, User notification channel preferences, Header bell & interactive dropdown, Mark all as read & batch prune, Security event alerts
Audit Trails	`audit-trails`	Security audit logging capturing actor context, IP addresses, events, and automated retention pruning.	`authorization`	—	—	—	`audit.view`	Enabled	Security & activity event tracking, Actor, IP, and user agent recording, Searchable audit log viewer, Automated log pruning command
Reporting	`reporting`	Read-only analytics dashboards, accessible SVG trend charts, date filtering, and streaming CSV exports.	`audit-trails`, `user-management`, `authorization`	—	—	—	`reports.view`, `reports.export`	Enabled	User growth & activity analytics, Audit event trend dashboards, Zero-dependency accessible SVG charts, Formula-safe streaming CSV export, Multi-day date range filtering

📦 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] Login
 [x] Logout
 [x] Registration
 [x] Email verification
 [x] Password reset
 [x] Password update
 [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

Include AI assistant guidelines?
 [x] AI assistant guidelines (.claude, .cursor, AGENTS.md, ...)

Non-Interactive Installation & Presets

The installer supports multiple flexible ways to configure features non-interactively in CI, local scripts, or project templates:

1. Named Presets (`--preset`)

Choose from pre-configured, validated feature profiles:

--preset=minimal — Core application with a minimal authentication surface (login, logout) and zero optional modules.
--preset=standard — Sensible default application (login, logout, registration, email-verification, password-reset, password-update with authorization, settings, user-management, notifications).
--preset=full — All supported authentication features and optional modules.

# Standard starter application
php artisan install:features --preset=standard --no-interaction

# Minimal authentication core
php artisan install:features --preset=minimal --no-interaction

# Full feature suite
php artisan install:features --preset=full --no-interaction

2. Reproducible Configuration File (`--answers-file`)

Provide an explicit JSON answers file for reproducible automation across environments and CI pipelines:

php artisan install:features --answers-file=starter-kit.json --no-interaction

Example starter-kit.json:

{
  "auth_features": [
    "login",
    "logout",
    "registration",
    "email-verification",
    "password-reset",
    "password-update"
  ],
  "optional_modules": [
    "authorization",
    "settings",
    "user-management",
    "notifications"
  ],
  "ai_guidelines": [
    "guidelines"
  ],
  "admin": {
    "name": "Administrator",
    "email": "admin@example.com",
    "password": "secret-password"
  }
}

3. Inline JSON Answers (`--answers`)

Pass a raw JSON string directly on the command line (backward compatible):

php artisan install:features --answers='{"auth_features":["login","logout","registration","email-verification","password-reset","password-update","two-factor"],"optional_modules":["authorization","settings","user-management","localization","notifications","audit-trails","reporting"],"ai_guidelines":["guidelines"]}' --no-interaction

Pass "ai_guidelines": [] (or "ai_guidelines": false) to decline and prune all maintainer AI configuration files (.agents, .ai, .amp, .claude, .codex, .cursor, .gemini, .junie, .mcp.json, AGENTS.md, CLAUDE.md, GEMINI.md, opencode.json, boost.json).

Precedence Order

When multiple answer sources are present, they are resolved in this deterministic order:

Explicit CLI Inline Answers (--answers='{...}')
Explicit CLI Answers File (--answers-file=path/to/file.json)
Explicit CLI Named Preset (--preset=standard)
Environment Inline Answers (CHISEL_ANSWERS or LARAVEL_INSTALLER_ANSWERS)
Environment Answers File (CHISEL_ANSWERS_FILE or LARAVEL_INSTALLER_ANSWERS_FILE)
Environment Named Preset (CHISEL_PRESET or LARAVEL_INSTALLER_PRESET)
Interactive Prompts / Defaults (multiselect prompt when interactive, or default questions when non-interactive)

Unselected modules and declined guidelines have all exclusive code, routes, permissions, translations, and configs cleanly pruned.

Post-Installation Self-Cleanup

Upon finishing execution, Chisel automatically cleans up the repository:

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

Note: InstallFeaturesCommand, SetupAdminUserCommand, chisel.php, and chisel-paths.php are installer-only infrastructure. They are used while creating the application via composer create-project and are automatically removed from the generated application after successful installation. Your generated project will not contain any of these files. SetupAuthorizationCommand and CreateAdminCommand are persistent runtime commands that remain available in the generated application when Authorization is enabled.

Generated Application Manifest (`starter-kit-manifest.json`)

Upon completing a successful and validated installation, Chisel records a non-secret configuration manifest at the project root (starter-kit-manifest.json).

This manifest serves as a machine-readable record for debugging, support requests, and future upgrade tooling. Generated applications are not required to consume this file at runtime (zero runtime overhead).

Key Guarantees:

Strictly Non-Secret: Contains no passwords, API tokens, database credentials, or secret environment blobs.
Versioned Schema: Includes schema_version (currently 1) to facilitate future tool compatibility.
Deterministic & Reproducible: Supports reproducible builds via standard environment variables (SOURCE_DATE_EPOCH, CHISEL_MANIFEST_TIMESTAMP, or CHISEL_DETERMINISTIC_MANIFEST).
Zero Runtime Dependencies: Plain JSON that can be inspected with standard tools (jq, json_decode()) without needing any installer classes.

Structure Overview:

{
  "schema_version": 1,
  "generated_at": "2026-11-02T22:00:00+00:00",
  "source_revision": "1c253c2...",
  "preset": "standard",
  "features": {
    "enabled": ["authorization", "teams", "api", "health-checks"],
    "pruned": ["billing", "notifications"]
  },
  "guidelines": {
    "enabled": ["ai", "actions", "queries", "rules", "wayfinder"]
  },
  "options": {
    "dry_run": false,
    "no_node": false
  }
}

🏛️ Installer Architecture & Responsibilities

The starter kit separates installer concerns into data, behavior, and orchestration:

Feature Metadata (App\Chisel\FeatureRegistry) — The authoritative single source of truth for all feature definitions (FeatureDefinition), paths, dependencies, Composer packages, and npm packages.
Dependency Validation (App\Chisel\Installer\DependencyValidator) — Pre-mutation validation that verifies required module dependencies and fails fast before mutations occur.
Composer Manifest & Lock Synchronization (App\Chisel\Installer\ComposerManifestPruner, App\Chisel\Installer\ComposerLockSynchronizer) — Modifies composer.json requirements and synchronizes composer.lock via dynamic candidate discovery.
Directory & Frontend Pruning (App\Chisel\Installer\DirectoryPruner, App\Chisel\Installer\FrontendPackagePruner, App\Chisel\Installer\FeaturePruner) — Handles safe directory pruning respecting protected directories and npm package pruning supporting LARAVEL_INSTALLER_NO_NODE.
Config & Infrastructure Cleanup (App\Chisel\Installer\ConfigCleaner, App\Chisel\Installer\Cleanup) — Cleans PHPStan NEON, PHPUnit XML, strips installer files, and ensures zero runtime installer overhead.
Chisel Orchestration (chisel.php) — Pure orchestration layer defining CLI prompts, life cycle, and feature delegation.
Chisel Paths (chisel-paths.php) — Framework-specific path configuration sourced authoritatively from FeatureRegistry.

➕ Developer Checklist: Adding a New Scaffolding Feature

Adding a new optional module or feature is simple and declarative:

Register Feature in FeatureRegistry: Add a FeatureDefinition to App\Chisel\FeatureRegistry::optionalModules() defining its key, label, sectionMarker, markerFiles, exclusiveFiles, emptyDirectories, composerPackages, frontendPackages, and dependencies.
Wire in chisel.php: The questions and dependency validation automatically discover features from FeatureRegistry. Wire the feature handler via ->selected('optional_modules', '<key>', then: fn($c) => FeaturePruner::applySelected($c, $feature), else: fn($c) => FeaturePruner::pruneUnselected($directory, $c, $feature)).
Handle Shared Packages: Use ->selectedAny('optional_modules', ['<feature1>', '<feature2>'], else: ...) for packages shared across multiple features.
Wrap Shared Code in Markers: Surround feature-specific routes, sidebar items, and type definitions with /* @chisel-<tag> */ and /* @end-chisel-<tag> */.
Verify with Pint & Pest: Run vendor/bin/pint --format agent and php artisan test.

🧪 Testing & Quality Control

Pre-Merge Verification (Complete Gate)

The authoritative pre-merge verification command runs linting, static analysis, type coverage, and the complete test suite with a 100% code coverage requirement:

# Complete authoritative pre-merge gate
composer test

Fast Local Commands

During active development, run targeted, fast local commands without redundant coverage or setup overhead:

# Fast parallel test run across all unit and feature tests (no coverage overhead)
composer test:quick

# Invariant, database-independent unit and architecture tests
composer test:unit

# Database-sensitive feature and query tests
composer test:database

# Invariant quality checks (linting, types, type coverage, unit tests)
composer test:quality

# Dependency compatibility and resolution verification
composer test:dependencies

# End-to-end browser tests (Playwright)
composer test:browser

# Full suite code coverage verification (100% required)
composer test:coverage

# Installer end-to-end scaffolding tests
composer test:installer

# Generated application smoke & performance budget verification
composer test:smoke

Performance Budgets for Generated Applications

Lightweight, deterministic performance budgets are established and continuously verified for representative generated application profiles (minimal, default, full):

Deterministic Query Budgets: Zero-query guarantee for minimal canonical endpoints (GET /, GET /login, GET /dashboard), and bounded query ceilings for default and full absorbing HandleSettings middleware, permissions, roles, and unread notifications.
Frontend Production Bundle Ceilings: Strict byte budgets for entry JavaScript (resources/js/app.tsx), entry CSS (resources/css/app.css), and total built bundle assets.
Flaky Timing Exclusion: Strictly deterministic metrics (query counts and file sizes) preventing flaky false positives on shared CI runners.

For complete baselines, metrics, and policy for updating budgets, see docs/performance-budgets.md.

CI Pipeline Architecture

Continuous Integration separates database-independent invariant checks from the database integration matrix:

quality (runs once): Installs dependencies, builds frontend assets, runs Pint/Rector/Vite+ linting, PHPStan & TypeScript checks, Pest type coverage (100%), database-independent unit & architecture tests, and full code coverage verification (100%).
dependencies (runs once): Verifies clean backend and frontend dependency resolution, strict lockfile reproducibility, supported PHP/toolchain constraints, and critical framework integration compatibility (package discovery, Wayfinder routes, asset compilation) without relying on pre-cached vendor or package stores.
database (matrix: SQLite, MySQL, PostgreSQL): Exercises database-sensitive feature and query behavior across supported database engines without repeating frontend, lint, or static-analysis overhead.
browser (runs once): Executes browser end-to-end tests on the canonical test database with Playwright.
installer-e2e (runs once): Validates Chisel scaffolding and project lifecycle generation.
installer-smoke (matrix: minimal, default, full): Generates and verifies real application lifecycles, database schema, frontend builds, TypeScript types, and lightweight performance budgets.

Architecture Constraints (Pest Arch)

The starter kit enforces structural and architectural boundaries through executable Pest architecture tests in tests/Unit/ArchTest.php:

Controllers:
- Application controllers in app/Http/Controllers must be final and readonly.
- Controllers must not be directly invoked or used by other classes in application code.
Actions:
- Actions in app/Actions must be final, readonly, and expose a handle() method.
- Actions expose handle() as their only public operation (with documented exception UpdateSettings::set() for single setting updates).
- Actions adhere to CRUD naming prefix conventions (Create, Update, Delete) with documented intentional exceptions (RecordAuditTrail, MarkAllNotificationsAsRead, MarkNotificationAsRead).
- Actions never return or depend on HTTP responses (RedirectResponse, JsonResponse, etc.).
Enums:
- All application enums must be defined in app/Enums, must be string-backed, and no enums may exist outside app/Enums.
Installer & Chisel Boundaries:
- Runtime application code (Actions, Http, Models, Queries, Enums, Rules, Services, Notifications, Data, Providers) must never depend on installer-only Chisel infrastructure (App\Chisel, Laravel\Chisel).
- Runtime console commands must not depend on Chisel infrastructure (only installer commands InstallFeaturesCommand and GenerateFeatureDocsCommand may use Chisel).
Cross-Feature Modular Boundaries:
- Optional feature modules follow strict acyclic dependency rules:
  - audit-trails does not depend on reporting or user-management.
  - settings does not depend on reporting or user-management.
  - notifications does not depend on reporting, audit-trails, or settings.
  - localization does not depend on other optional feature modules.
  - user-management does not depend on reporting.
Test Suite Organization:
- HTTP controller and middleware tests belong strictly in tests/Feature, never in tests/Unit.

📁 Key Directory Structure

├── app/
│   ├── Actions/                  # Reusable business logic actions
│   ├── Console/Commands/         # Artisan commands
│   │   ├── CreateAdminCommand.php        # 🛡️ Super Admin user creation & promotion
│   │   ├── GenerateFeatureDocsCommand.php # ⚙️ Installer-only (removed after install)
│   │   ├── InstallFeaturesCommand.php    # ⚙️ Installer-only (removed after install)
│   │   ├── SetupAuthorizationCommand.php # 🛡️ Authorization runtime synchronization
│   │   └── SetupAdminUserCommand.php     # ⚙️ Installer-only (removed after install)
│   ├── 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                    # ⚙️ Installer-only feature pruning (removed after install)
├── 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.

tooinfinity / infinity-starter-kit

Package info

Security

Statistics

README

⚡ Tech Stack

📋 Supported Runtime & Toolchain Versions

🚀 Quick Start

1. Create a New Project

2. Select Your Features

Dry-Run Mode (Preview Planned Mutations)

3. Authorization & Super Admin (if enabled)

4. Start Development

🛠️ Implemented Modules

🔐 Authentication Module

🛡️ Authorization & RBAC Module

Architecture

Key Design Decisions

Permission Enum

Role Enum

Super Admin Bypass

Form Request Authorization

Frontend Authorization

Chisel Pruning

📊 Reporting & Analytics Module

Implemented Reports

Key Design Decisions

Chisel Pruning

🧩 Chisel-Based Scaffolding & Feature Installation

Feature Categories

🗺️ Feature Compatibility Matrix

📦 Installation Flow

Non-Interactive Installation & Presets

1. Named Presets (--preset)

2. Reproducible Configuration File (--answers-file)

3. Inline JSON Answers (--answers)

Precedence Order

Post-Installation Self-Cleanup

Generated Application Manifest (starter-kit-manifest.json)

🏛️ Installer Architecture & Responsibilities

➕ Developer Checklist: Adding a New Scaffolding Feature

🧪 Testing & Quality Control

Pre-Merge Verification (Complete Gate)

Fast Local Commands

Performance Budgets for Generated Applications

CI Pipeline Architecture

Architecture Constraints (Pest Arch)

📁 Key Directory Structure

📄 License

1. Named Presets (`--preset`)

2. Reproducible Configuration File (`--answers-file`)

3. Inline JSON Answers (`--answers`)

Generated Application Manifest (`starter-kit-manifest.json`)