ai-web/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• app/ contains application logic (controllers, models, services).
• resources/views/ stores Blade templates for public pages and admin UI.
• routes/web.php defines frontend/admin routes.
• database/migrations/ contains schema and data migration files.
• tests/Feature/ and tests/Unit/ hold feature and unit tests.
• public/ serves static assets; uploaded files are exposed via public/storage.

Build, Test, and Development Commands

• composer install installs PHP dependencies.
• npm install installs frontend dependencies.
• composer run dev starts local Laravel + Vite development workflow.
• php artisan migrate runs database migrations.
• composer test clears config and runs test suite.
• php artisan storage:link creates the /storage public symlink for uploads.

Coding Style & Naming Conventions

• Follow PSR-12 for PHP; use 4-space indentation.
• Use strict types (declare(strict_types=1);) in PHP files.
• Class names: PascalCase; methods/variables: camelCase; constants: UPPER_SNAKE_CASE.
• Blade components should be reusable and grouped by domain (e.g. resources/views/components/portal/).
• Keep controller actions focused; extract reusable logic to private methods/services.

Testing Guidelines

• Write unit tests for pure logic in tests/Unit/.
• Write feature tests for routes/forms/permissions in tests/Feature/.
• Name tests by behavior, e.g. test_admin_can_update_home_modules.
• Run composer test before opening a PR.

Commit & Pull Request Guidelines

• Use clear, scoped commit messages, e.g. feat(admin): add structured home module settings.
• Keep commits focused; avoid mixing unrelated refactors.
• PRs should include:
  • What changed and why
  • Screenshots/GIFs for UI updates
  • Migration/rollback notes if schema changes
  • Test coverage notes or manual verification steps

Security & Configuration Tips

• Never commit .env or secrets.
• Ensure APP_URL is correct in each environment.
• For markdown/image uploads, prefer relative /storage/... paths to avoid host lock-in.
• Validate all admin inputs (URL type, route whitelist, required fields) before persistence.