# Repository Guidelines

## Project Structure & Module Organization
- `src/` layers PHP code (`Application`, `Domain`, `Framework`, `Infrastructure`); create new classes under the matching namespace and keep adapters in Infrastructure.
- `resources/` stores Vite-managed frontend code (`resources/js`, `resources/css`), while build artifacts belong in `public/assets` under the `public/` web root.
- `tests/` mirrors the PHP namespaces and houses Playwright suites in `tests/e2e`; share fixtures and stubs through `tests/Support`.
- Operational docs and tooling sit in `docs/`, `docker/`, and `deployment/`; update those paths whenever runtime behaviour changes.

## Build, Test & Development Commands
- `make up` / `make down` manage the Docker stack; add `make logs` when you need container output.
- `npm run dev` starts Vite locally, and `npm run build` produces optimized bundles into `public/assets`.
- `make test` drives the full Pest suite; use `make test-unit`, `make test-domain`, or `make test-coverage` for focused runs.
- JavaScript and browser checks run via `npm run test`, `npm run test:e2e`, and `npm run test:coverage`.
- Quality gates: `make phpstan`, `make cs` (dry run), `make cs-fix` (auto-fix), plus `npm run lint:js` and `npm run format`.

## Coding Style & Naming Conventions
- Follow PSR-12 with strict types; prefer constructor injection and suffix integrations with their role (`MailerAdapter`, `RedisCache`).
- Keep PHP objects immutable unless Domain logic requires mutation; colocate interfaces with their consuming layer.
- Use 4-space indents in PHP and Prettier defaults for TypeScript; name frontend components in PascalCase and utilities in camelCase.

## Testing Guidelines
- Add Pest specs beside the feature namespace with expressive names (`it_handles_invalid_tokens`); keep builders in `tests/Support`.
- Mock external services through `tests/__mocks__`; rely on Pest datasets for edge cases.
- Sync Playwright specs with UX changes, reuse `tests/e2e/fixtures`, and review reports via `playwright show-report`.

## Commit & Pull Request Guidelines
- Use Conventional Commits (`fix:`, `feat:`, optional scope) to match history.
- PRs must outline the change, list executed checks, and link issues; attach screenshots for UI work or config diffs for ops updates.
- Confirm CI covers Pest, Jest, Playwright, PHPStan, and php-cs-fixer before requesting review.

## Security & Configuration Tips
- Never commit `.env` or secrets; follow `ENV_SETUP.md` and store deployment credentials in Vault.
- Run `make security-check` ahead of releases and reflect infrastructure changes in `docs/deployment/`.
