# Repository Guidelines

## Project Structure & Module Organization
Laravel services sit in `app/`, domain logic in `Domain/`, and adapters (queues, integrations, notifications) in `infra/`. Use `routes/api.php` for JSON endpoints and `routes/web.php` for server-rendered flows. Blade/Vite assets remain in `resources/`; migrations, factories, and seeders share `database/`; automated checks are in `tests/`. Store reusable blueprints in `stubs/` and centralize configuration under `config/`.

## Build, Test, and Development Commands
- `composer install && npm install` — install dependencies; re-run whenever lockfiles change.
- `php artisan serve` or `./vendor/bin/sail up` — start the HTTP stack locally; Sail provides the Dockerized services.
- `npm run dev` / `npm run build` — run the Vite watcher or create production-ready assets.
- `php artisan migrate --seed` — migrate and seed the database once `.env` credentials are configured.

## Coding Style & Naming Conventions
Target PHP 8.2 and PSR-12 spacing (4-space indent, braces on new lines). Organize domain classes under `Domain/<Context>/` and name controllers `VerbSubjectController`. Favor camelCase for methods, snake_case for database columns, and strict typing. Run `./vendor/bin/pint` before every commit and use read-only DTOs on boundaries. JavaScript modules in `resources/js` should be ES modules named after the feature directory (for example `resources/js/notifications/index.js`).

## Testing Guidelines
Feature and unit suites live in `tests/Feature` and `tests/Unit`. Pest is enabled, so prefer `./vendor/bin/pest` (or `./vendor/bin/pest --coverage`) over `phpunit`. Name files `<Subject>Test.php`, use descriptive `it('does ...')` blocks, and cover happy and sad paths. Replace outbound calls with Laravel HTTP fakes or `infra/` mocks because CI cannot reach external services. Schema changes require migration tests plus database assertions.

## Commit & Pull Request Guidelines
Commits in history use ticket-prefixed subjects (for example `REX-1311 Fix address creation bug`); keep the `<TICKET> <summary>` format and limit each commit to one concern. Squash WIP commits before opening a PR. Every PR should explain the problem, solution, and side effects, link the tracker ticket, and attach screenshots or payload samples for UI/API shifts. Describe validation steps and request review only after Pint, Pest, artisan tests, and Vite builds succeed locally.

## Security & Configuration Tips
Never commit `.env`, credentials, or downloaded certificates. Bootstrap environments with `cp .env.example .env` then `php artisan key:generate`. Queue, Expo, and Slack tokens belong in `.env` (use `REX_` prefixes) and should be injected through Docker/Sail when possible. Scrub sensitive payloads before posting snippets from `storage/logs/`, and rotate keys immediately if accidental commits occur.