# Project Guidelines

This document describes coding, naming, and architectural guidelines for the project.

## Frontend

### React pages
- Location: `resources/js/Pages`
- Structure your React pages to mirror your URL / Controller structure.

### React components
- Location: `resources/js/Components`
- Keep reusable UI components (Buttons, Modals, Tables) here.
- Use PascalCase for component filenames and exports. Example:

```jsx
// good: resources/js/Pages/Users/Index.jsx
function UsersIndex() { /* ... */ }
export default UsersIndex;
```

## Audit logs
- Track who created, updated, or deleted records.
- Recommended packages:
  - `spatie/laravel-activitylog`
  - `owen-it/laravel-auditing`

## Emails & Settings
- All emails should be sent via the `disburseMail` helper.
- All application settings should be retrieved via the `settings` helper.

## API endpoints
- All API endpoints should use the helpers `api_response` and `error_response`.
- Validation must be performed in FormRequest classes.
- GET endpoints should return data using the response helpers.

## Testing (Pest)
When writing Pest tests, follow these rules strictly:

1. Method naming
   - Use camelCase and make names readable. Example: `testGuestCannotSeePost`.

2. Test coverage lifecycle
   - Each feature should be covered for the following lifecycle hooks:
     a. Create: Assert that validated data exists in the database after creation.
     b. Read: Assert that created/updated data is returned to the consumer as expected.
     c. Update: Assert the updated values exist in the DB.
     d. Delete: Use soft deletes and assert `deleted_at` is not null in the DB.
     e. Reactivate: Assert `deleted_at` is restored to `null` after reactivation.

## Permissions
- Recommended: `spatie/laravel-permission` (package: `spatie/laravel-permission`).
- Every endpoint (create, edit, update, delete, reactivate) must have a corresponding permission.
- All action buttons in views should be shown/hidden based on the user's permissions.

## Controllers
- Use singular PascalCase for controller filenames. Example: `UserController.php` (not `UsersController.php`).
- Controllers should primarily:
  - handle routing,
  - accept validated data from `FormRequest` classes,
  - pass data to Service classes or return Inertia responses.

## Models
- Use Eloquent models for relationships, fillable attributes and DB logic.
- Method names inside models should be singular and camelCase (example: `studentCourse`).
- All DB queries related to an entity should be implemented on the model.

## Route URLs
- Route names/URLs should be plural.
- Use `kebab-case` when a multi-word segment is required. Example: `/client-portal/messages`.

## Functions and Variables
- Function names (helpers, plain PHP functions) should use `snake_case`.
- Variable names should use `camelCase` and be descriptive.

## Single Responsibility
- A class or method should have a single responsibility. Keep functions small and focused.