# Top Star Driving CRM

Laravel 13 admin app (PHP 8.5, MySQL). Admin area lives under `/admin`.
New pages are React (Inertia); the original admin pages are still Blade (Velzon / Bootstrap 5).

## Stack
- Back end: Laravel 13, session guard `admin` (model `App\Models\Admin`), Inertia (`inertiajs/inertia-laravel` ^3).
- Front end: React 19, TypeScript (strict), Tailwind 4 (prefixed utilities only), Vite 8.
- Tooling: ESLint 9 + Prettier (front end), Pint (PHP style), Larastan (static analysis), Pest 4 (tests).
- There is NO Vue, no Pinia/Vuex, no starter-kit auth (Fortify/register). Do not add them.

## Where things go
- React pages: `resources/js/pages/<name>.tsx` (page name = path, e.g. `Inertia::render('dashboard')`).
- React layouts/components/hooks/types: `resources/js/{layouts,components,hooks,types}`.
- Blade admin pages: `resources/views/themes/backend/pages/<module>/` (shared components in `resources/views/components`).
- Inertia root view: `resources/views/themes/backend/layouts/inertia.blade.php` — it extends the Velzon admin layout, so React pages get the same header, left menu, top bar and footer as Blade pages.
- Design tokens: `resources/css/theme.css` is the single source (colours, radius, fonts).
  `blade.css` is the stylesheet loaded on every admin page (no preflight, utilities prefixed: `tw:flex`).
- UI split: the ADMIN area (Blade and React pages) uses Velzon/Bootstrap. Tailwind 4 + shadcn/ui is planned for the
  public-facing FRONTEND pages (none yet). When they arrive, add a separate `app.css` (full Tailwind), their own root
  view/layout and the shadcn CLI setup (`components.json`); never load a Tailwind reset inside the admin shell.
- React pages are styled with Velzon/Bootstrap classes (`card`, `row`, `btn`...), like the Blade pages.
  Shared React pieces: `layouts/velzon-layout.tsx` (page-content wrapper + flash), `components/page-title.tsx`.

## Rules
- React page -> `$this->renderReact('<page>', $title, '<breadcrumb name>', $props)` (wraps `Inertia::render`, adds title/breadcrumbs).
  Blade page -> `view(...)`. Do not mix in one controller action.
- The left menu is built by the Blade `MenuComposer` for both kinds of page; menu items need no extra React wiring.
- Every admin route goes inside the `['admin', 'admin.access']` group; React routes also add `->middleware('inertia')`.
- Permissions are enforced SERVER-SIDE by the `admin` middleware (`RedirectIfNotAdmin` + role rights tables).
  The shared `auth.permissions` prop is only for hiding UI; never rely on it for access control.
  Role 1 (Super Administrator) bypasses rights checks.
- A new admin page needs rows in `modules` / `module_methods` (+ rights) via the seeders;
  `php artisan admin:audit-permissions` must report no gaps.
- Type every Inertia page's props in TypeScript (no `any`; ESLint enforces it).
  Shared props are typed in `resources/js/types/global.d.ts`.
- Use `config()` not `env()` outside `config/`.
- Do not edit `.env` secrets. Never run `migrate:fresh` / `db:wipe` / destructive commands against a real DB without asking.
- Tests never touch MySQL: `phpunit.xml` uses in-memory SQLite. DB tests use `RefreshDatabase`.

## Commands
```bash
# setup
composer install && npm install
cp .env.example .env && php artisan key:generate
php artisan migrate --seed

# develop
npm run dev                 # Vite dev server
npm run build               # production assets -> public/build

# front end checks
npm run types:check         # tsc --noEmit
npm run lint                # ESLint   (lint:fix to auto-fix)
npm run format:check        # Prettier (format to write)

# PHP checks
composer lint               # Pint, changed files only (composer format to fix)
composer analyse            # Larastan (level 5 + phpstan-baseline.neon)
composer test               # Pest
composer check              # lint + analyse + test
```

## Notes
- Pint/Larastan are scoped so legacy code does not block work: `composer lint` only checks files changed in git,
  and old Larastan findings live in `phpstan-baseline.neon`. Don't grow the baseline; fix new findings.
- `public/build` is git-ignored; `deploy-build.sh` builds and rsyncs it to the dev server.
- Pest 4 is kept (Pest 5 not yet adopted); the project now requires PHP 8.5 (`brew install php`). TypeScript is pinned to 6.0 (typescript-eslint
  does not support 7 yet) and ESLint to 9 (eslint-plugin-react does not support 10 yet).
