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.

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.

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.

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.

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.

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