KSA-ORACLE/WARP.md

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project summary: Laravel 12 backend with Vue 3 + Inertia.js (TypeScript) frontend, Vite build, Tailwind CSS 4, Pest for testing, Laravel Pint for PHP style. CI runs linting and tests on develop/main.

Common commands

• Initial setup

composer install
npm install
cp .env.example .env
php artisan key:generate
php artisan migrate

• Development servers

# Full stack (PHP server, queue listener, logs, Vite dev)
composer run dev

# Full stack with SSR renderer (builds SSR bundle, starts SSR service)
composer run dev:ssr

# Alternatively run pieces individually
npm run dev               # Vite dev server
php artisan serve         # Laravel HTTP server
php artisan queue:listen  # Queue worker for async jobs

• Build assets

npm run build       # Client bundle
npm run build:ssr   # Client + SSR bundle

• Lint and format

# PHP code style (Laravel Pint)
vendor/bin/pint

# Frontend format (Prettier)
npm run format           # write fixes
npm run format:check     # check only

# Frontend lint (ESLint)
npm run lint             # with --fix per eslint.config.js

• Tests (Pest)

# Run all tests
./vendor/bin/pest

# Run tests in a file or directory
./vendor/bin/pest tests/Feature/DashboardTest.php

# Filter by test name or pattern
./vendor/bin/pest --filter "authenticated users can visit the dashboard"

# Alternative (uses artisan test via composer)
composer run test

Architecture overview

• HTTP and routing

  • routes/web.php defines the entry routes, rendering Inertia pages: Welcome and an auth-protected Dashboard. It includes routes/auth.php (auth flows) and routes/settings.php (Profile, Password, Appearance pages).
  • Controllers live under app/Http/Controllers with Auth/* and Settings/* for user flows. ProfileController uses a typed FormRequest (ProfileUpdateRequest) for validation; PasswordController validates current_password and updates via Hash.

• Inertia + SSR integration

  • Inertia middleware (app/Http/Middleware/HandleInertiaRequests.php) sets the root view to app and shares global props: app name, a random quote, the authenticated user, and sidebarOpen state derived from a cookie.
  • SSR is enabled in config/inertia.php ('ssr.enabled' => true) and expects a renderer at http://127.0.0.1:13714. The SSR entry is resources/js/ssr.ts; use composer run dev:ssr or php artisan inertia:start-ssr after building the SSR bundle.
  • The Blade root template resources/views/app.blade.php injects Vite assets and adds an inline theme bootstrap so dark mode applies before Vue mounts.

• Frontend structure (Vue 3 + TypeScript)

  • Inertia app bootstrap is in resources/js/app.ts (resolvePageComponent to resources/js/pages/**/Name.vue). It sets document titles and a progress bar.
  • Pages under resources/js/pages/ render into layouts in resources/js/layouts (for instance, AppLayout wraps AppShell). Global shell and sidebar behavior derive from $page.props shared by middleware.
  • Composables (resources/js/composables) include useAppearance for light/dark theme initialization used on page load.
  • UI components live under resources/js/components (with a shadcn-vue setup configured by components.json). TypeScript path alias @/* points to resources/js/* (see tsconfig.json).

• Build and tooling

  • Vite config (vite.config.ts) wires laravel-vite-plugin, Tailwind CSS 4, Vue plugin, and @laravel/vite-plugin-wayfinder. Entry points: resources/js/app.ts (client) and resources/js/ssr.ts (SSR). Wayfinder provides typed route helpers for the frontend based on backend routes.
  • Tailwind is configured for v4 with plugins; Prettier plugins include organize-imports and tailwindcss to keep classes ordered.
  • ESLint (eslint.config.js) enables Vue + TypeScript rules and ignores vendor, node_modules, public, bootstrap/ssr, tailwind.config.js, and resources/js/components/ui/*.

• Data, auth, and testing

  • Authentication uses the default 'web' session guard (config/auth.php). The User model (app/Models/User.php) uses hashed passwords and standard fillables. Email verification is supported via MustVerifyEmail checks in profile flows.
  • phpunit.xml configures an in-memory SQLite database and testing environment variables, so tests run without external DB setup.
  • Tests are written with Pest (tests/Feature, tests/Unit). tests/Pest.php binds Tests\TestCase and includes example expectations.

• CI signals (reference)

  • .github/workflows/lint.yml runs Laravel Pint, Prettier format, and ESLint on develop/main branches.
  • .github/workflows/tests.yml installs dependencies, builds assets, and runs Pest. Node 22 and PHP 8.4 are used in CI.