FilamentLaravel/README.md

# FilamentLaravel

A Laravel 12 application scaffolded with Jetstream and Livewire, built with Vite and Tailwind CSS. This repo includes common local‑dev conveniences (concurrent processes for PHP server, queue worker, logs, and Vite) and a modern testing setup using Pest.

If you’re new to this codebase, this README helps you get it running locally and understand where things live.

> Note: The project name in `.env` is `APP_NAME=FilamentApp`. The repository name is `FilamentLaravel`.

## Stack

- Language: PHP ^8.2
- Framework: Laravel ^12.0
  - Jetstream ^5.3
  - Sanctum ^4.0
  - Livewire ^3.x and Livewire Flux ^2.x
- Frontend tooling: Vite ^6, Tailwind CSS ^4, PostCSS
- Package managers: Composer (PHP), npm (Node)
- Testing: Pest ^3 (with PHPUnit under the hood)

## Requirements

- PHP 8.2+
- Composer 2.x
- Node.js 18+ and npm 9+
- A database (MySQL/MariaDB). Defaults from `.env`:
  - `DB_HOST=127.0.0.1`, `DB_PORT=3306`, `DB_DATABASE=filamentlaravel`, `DB_USERNAME=root`, `DB_PASSWORD=ServBay.dev`
- Optional services depending on features you use:
  - Redis (default client configured: `phpredis`)
  - Mail catcher or SMTP server (defaults to `MAIL_MAILER=log`)

## Quick start

1. Clone and install dependencies
   ```bash
   git clone <your-fork-or-repo-url>
   cd FilamentLaravel
   composer install
   npm install
   ```
2. Configure environment
   ```bash
   cp .env.example .env   # if .env doesn’t exist
   php artisan key:generate
   ```
   - Update `.env` database credentials as needed.
   - Ensure `SESSION_DRIVER=database` (already set) and run migrations (next step) to create the sessions table.
3. Create database and run migrations
   ```bash
   php artisan migrate
   ```
4. Run the app (all-in-one dev experience)
   ```bash
   composer run dev
   ```
   This starts:
   - `php artisan serve` (Laravel app)
   - `php artisan queue:listen --tries=1` (queue worker)
   - `php artisan pail --timeout=0` (pretty app logs)
   - `npm run dev` (Vite)

   Or run them individually:
   ```bash
   php artisan serve
   npm run dev
   ```

5. Visit the app at the URL shown by `php artisan serve` (defaults to `http://127.0.0.1:8000`). You can also set `APP_URL` in `.env`.

## Scripts

- Composer
  - `composer run dev` — concurrently run server, queue worker, logs, and Vite
- npm
  - `npm run dev` — start Vite in dev mode
  - `npm run build` — build frontend assets for production

## Environment variables

See `.env` for all variables. Common ones:

- Application
  - `APP_NAME` (default: `FilamentApp`)
  - `APP_ENV` (`local`, `production`, ...)
  - `APP_DEBUG` (true/false)
  - `APP_URL` (default: `http://localhost`)
  - `APP_LOCALE`, `APP_FALLBACK_LOCALE`
- Logging
  - `LOG_CHANNEL` (default: `stack`), `LOG_LEVEL`
- Database (MySQL by default)
  - `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`
- Cache/Queue/Session
  - `CACHE_STORE=database`
  - `QUEUE_CONNECTION=database`
  - `SESSION_DRIVER=database`, `SESSION_LIFETIME`
- Redis
  - `REDIS_CLIENT=phpredis`, `REDIS_HOST`, `REDIS_PORT`
- Mail
  - `MAIL_MAILER=log`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_FROM_*`
- AWS (only if you enable S3, etc.)
  - `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `AWS_BUCKET`
- Vite
  - `VITE_APP_NAME` (default mirrors `APP_NAME`)

## Project structure (selected)

- `app/` — application code (models, controllers, policies, jobs, etc.)
- `bootstrap/` — framework bootstrap files
- `config/` — application configuration
- `database/` — migrations, factories, seeders
- `public/` — public web root (entry: `public/index.php`)
- `resources/` — Blade views, CSS, JS
  - `resources/css/app.css` — Tailwind entry
  - `resources/js/app.js` — JS entry (referenced by Vite)
  - `resources/views/...` — Blade templates (includes Livewire components)
- `routes/`
  - `web.php` — web routes
  - `api.php` — API routes
- `tests/` — test suite (Pest)
- `vite.config.js` — Vite configuration
- `artisan` — Laravel CLI
- `composer.json` / `package.json` — dependencies and scripts

## Development notes

- Vite HMR refresh is enabled via `laravel-vite-plugin` with inputs `resources/css/app.css` and `resources/js/app.js`.
- Sessions, cache, and queue default to database-backed stores. Ensure migrations are run.
- Jetstream is installed. The chosen Jetstream stack (Livewire vs Inertia) isn’t explicitly declared here — Livewire is present. See `composer.json` and `resources/views` for details.

## Testing

Run the test suite:
```bash
php artisan test
# or
./vendor/bin/pest
```

You can create tests under `tests/` using Pest’s syntax.

## Deployment

- Build frontend assets:
  ```bash
  npm run build
  ```
- Ensure `APP_ENV=production`, `APP_DEBUG=false`, correct `APP_URL`, and proper cache/queue/mail configurations.
- Run database migrations on deploy:
  ```bash
  php artisan migrate --force
  ```

### Docker (optional)
Laravel Sail is included as a dev dependency. If you prefer Docker, you can set up Sail. This repository does not include a prepared Sail config in this README.

## Entry points

- HTTP: `public/index.php` (served via the web server or `php artisan serve`)
- CLI: `artisan`
- Frontend dev server: `npm run dev` (Vite)

## TODOs / Unknowns

- Production deployment target and steps (server, PaaS, container registry) — TODO
- Domain and HTTPS/TLS configuration — TODO
- Mail provider and credentials for non‑log mailers — TODO
- Storage driver(s) for user uploads (local vs S3) — TODO
- Background jobs in production (e.g., Supervisor, Horizon) — TODO
- Any seeded demo data or default admin user — TODO

## License

This project is open-sourced software licensed under the MIT license. See `composer.json` for the declared license.