# 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`.

## 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.