# Project Rules

## 1) Architecture
- Use service-layer architecture: Controller -> Service -> Model.
- Keep controllers thin; business logic belongs in services.
- Keep request validation in FormRequest classes, not in controllers.

## 2) Routing & API
- Keep API routes separated by surface:
  - `routes/api/client.php`
  - `routes/api/dashboard/admin.php`
  - `routes/api/general.php`
- Protect dashboard routes with proper auth/permission middleware.
- Return consistent JSON responses using the project response helpers.

## 3) Validation
- Always validate input with FormRequest classes.
- For phone fields, enforce country-based phone length using `phone_code` and `countries.phone_limit`.
- Add clear validation messages for user-facing errors.

## 4) Settings (Source of Truth)
- Runtime settings must come from database-backed settings when available.
- Use `settings()` / `setting()` helper or `SettingService` for reading settings.
- Keep fallback to config values only when DB setting is missing.
- New configurable behavior must have a setting key in `SettingKeyEnum`.

## 5) Payment Module Rules
- Payment module code remains isolated under `modules/Payment`.
- Gateway credentials and runtime payment options should be DB-driven first.
- Currency, wallet min/max limits, and payment mode must be read through payment settings resolver.
- Keep gateway-specific logic inside gateway classes.

## 6) Database & Migrations
- Never edit old migrations in a way that breaks existing environments.
- For new behavior on existing systems, add new migrations that backfill needed data.
- Add indexes/constraints when required by query or integrity needs.

## 7) Enums & Constants
- Prefer enums for fixed keys, statuses, and groups.
- If a new setting is introduced, update group/type/default/label mappings.

## 8) Middleware & Authorization
- Enforce user type and role/permission checks via middleware and policies.
- Do not duplicate authorization logic across controllers.

## 9) Code Quality
- Follow PSR-12 formatting.
- Keep methods focused and small.
- Avoid duplicated logic; extract reusable helpers/services.
- Add/adjust tests when behavior changes.

## 10) Documentation
- Update docs when changing architecture, commands, or behavior.
- Keep implementation docs in `docs/` and make examples runnable.

## 11) Artisan Command Changes
- Command arguments/options must be explicit and validated.
- Document command signature changes in `README.md`.

## 12) Command Facilities
- Every custom command should provide:
  - clear signature (required args + optional flags)
  - short description and practical usage examples
  - strong input validation with clear errors
- Use safe execution patterns:
  - confirmation prompts before destructive actions
  - `--force` only for explicit overwrite/skip-confirm behavior
- File-generation commands must:
  - create missing directories safely
  - skip existing files by default
  - overwrite only when `--force` is used
  - print clear logs for created/skipped/updated files
- Keep commands orchestration-focused:
  - move reusable business logic to services/helpers
  - avoid large logic blocks inside command classes
- Any command change must be reflected in docs:
  - `README.md`
  - related files in `docs/`
- Existing custom commands in this project:
  - `php artisan make:crud` - scaffold admin CRUD resources/files.
  - `php artisan revert:crud` - remove files/routes generated by `make:crud`.
  - `php artisan make:user-type` - scaffold a user type (`user` or `dashboard` scope).
  - `php artisan make:user-type:revert` - revert generated user type files/config/routes.
  - `php artisan make:ai-seeder` - generate seeder from DB schema via AI flow.
  - `php artisan postman:generate` - generate Postman collection from routes.
  - `php artisan permission:clear-cache` - clear permission cache globally or selectively.
  - `php artisan translations:find` - find/scan translation keys usage.
  - `php artisan fcm:debug` - check/debug FCM configuration.
  - `php artisan fcm:test {token}` - send FCM test notification to a device token.

## 13) Backward Compatibility
- Prefer additive changes.
- Keep safe fallbacks to avoid breaking production deployments.