# Repository Guidelines

## Project Structure & Module Organization

This is a Laravel 13 application for an event-planning consultancy. Application code lives in `app/`: domain rules belong in `app/Domain`, HTTP entry points in `app/Http`, and the internal Filament 5 panel in `app/Filament`. Blade views, JavaScript, and Tailwind CSS are under `resources/`; Vite publishes browser assets to `public/`. Database migrations, factories, and seeders live in `database/`. Tests are grouped into `tests/Unit`, `tests/Architecture`, `tests/Feature`, and `tests/Browser`. Treat `SPEC.md` as the product source of truth and use `openspec/` for planned changes.

## Build, Test, and Development Commands

- `composer setup` installs PHP and npm dependencies, creates `.env`, migrates, and builds assets.
- `docker compose up -d` starts the local PostgreSQL service.
- `composer dev` runs Laravel, the queue listener, logs, and Vite together.
- `npm run build` creates the production frontend bundle.
- `composer quality` runs formatting checks, PHPStan level 5, dependency audit, and every test suite.
- `composer test:unit`, `composer test:feature`, or `composer test:browser` run focused suites.

Feature and browser tests require the `amare_test` PostgreSQL database configured in `phpunit.xml`.

## Worktrees

Always work in a git worktree created from the `main` ref — never modify `main` directly and never commit from the primary working tree. Create a dedicated worktree per feature/branch with `git worktree add -b <branch> <path> main`. On finishing work, create a PR, watch CI until green, then merge it. Clean up the worktree with `git worktree remove` after merge.

## Git Hooks (husky)

Hooks live in `.husky/` and auto-install on any plain `npm install` via the `prepare` script. Note `composer setup` runs `npm install --ignore-scripts`, which skips hook installation — after setup, run `npm install` once (or `npx husky`) to activate hooks.

- `pre-commit`: runs `composer pint:check` and `composer phpstan`.
- `pre-push`: gates on the `amare_test` database (settings parsed from `phpunit.xml`), blocks the push with a `docker compose up -d` hint when Postgres is unreachable, then runs `composer test:unit` and `composer test:feature`. Browser tests are CI-only (FrankenPHP container).

## Coding Style & Naming Conventions

Follow PSR-4 and Laravel conventions: PascalCase classes, camelCase methods, and snake_case database columns. Use four spaces (two in YAML, except four in Compose files), LF endings, and UTF-8 as defined by `.editorconfig`. Every project-owned PHP file must place `declare(strict_types=1);` immediately after `<?php`. Keep domain code independent of Filament and Livewire. Run `composer pint` to format and `composer phpstan` before review.

## Testing Guidelines

Tests use Pest 4; browser coverage uses Pest Browser/Playwright. Name files by behavior, ending in `Test.php`, and add tests in the suite matching the changed layer. Feature tests use `RefreshDatabase`. Add architecture coverage for dependency-boundary changes. No numeric coverage threshold is enforced, but changed behavior must have regression coverage.

## Commit & Pull Request Guidelines

History follows Conventional Commit-style subjects, for example `feat: Fase 0 — Fundação`. Use `<type>: <imperative summary>` (`feat`, `fix`, `docs`, `test`, `chore`) and keep commits focused. Pull requests should explain scope, link the relevant issue or OpenSpec requirement, list verification commands, and include screenshots for UI changes. Ensure all CI jobs pass.

## Security & Configuration

Copy `.env.example`; never commit secrets or production credentials. Development seed credentials are local-only. Validate uploads and authorization through Laravel policies, and run `composer security-audit` after dependency changes.