# Project Conventions

## Test database safety

- Tests must use SQLite `:memory:` through `tests/bootstrap.php` and `Tests\TestCase`.
- Never run tests, `migrate:fresh`, `migrate:refresh`, or `db:wipe` against a persistent database, including the developer's `shopit` database.
- Never bypass the connection safety guard to resolve test failures. Use `php tests/verify-database-safety.php` to verify isolation without queries or migrations.

## Architecture

This project uses a domain-oriented structure grouped by business area under
`app/Domains`. Cross-cutting modules live under `app/Shared`.

Business domains must live in:

```text
app/Domains/<Area>/<DomainName>/
```

The current areas are `Core`, `Commerce`, and `Ticketing`. Cross-cutting
modules live in `app/Shared/<ModuleName>/`.

Supported folders inside each domain:

```text
app/Domains/<Area>/<DomainName>/
├── Models/
├── Controllers/
├── Requests/
├── Resources/
├── Services/
├── Policies/
├── Exceptions/
└── routes/
```

## Routing

- Root API routes live in `routes/api.php`.
- `routes/api.php` should act as an aggregator only.
- Each business domain defines its own routes in
  `app/Domains/<Area>/<DomainName>/routes/api.php`.
- Shared modules that expose routes define them in
  `app/Shared/<ModuleName>/routes/api.php`.

## Namespaces

Use this namespace pattern:

```php
App\Domains\<Area>\<DomainName>\Models
App\Domains\<Area>\<DomainName>\Controllers
App\Domains\<Area>\<DomainName>\Requests
App\Domains\<Area>\<DomainName>\Resources
App\Domains\<Area>\<DomainName>\Services
App\Domains\<Area>\<DomainName>\Policies
App\Domains\<Area>\<DomainName>\Exceptions
```

For cross-cutting modules, use `App\Shared\<ModuleName>\...`. Reusable enums
and rules live directly under `App\Shared`.

## Responsibilities

- `Models/`: Eloquent models and model relationships.
- `Controllers/`: HTTP entrypoints only.
- `Requests/`: validation and request authorization with `FormRequest`.
- `Resources/`: API response transformation with `JsonResource`.
- `Services/`: business logic and application workflows.
- `Policies/`: authorization rules.
- `Exceptions/`: domain-specific exceptions.
- `routes/`: domain route definitions.

## Controller Rules

- Controllers should stay thin.
- Do not validate inline in controllers when a `FormRequest` can be used.
- Do not place business logic in controllers.
- Prefer returning `JsonResource` or resource collections instead of raw models.

## Model Rules

- Models must stay inside their domain.
- Cross-domain relations are allowed when the dependency is explicit and necessary.
- Preserve existing table names and key mappings when the database uses legacy names.

## Naming Rules

- Domains use singular English names such as `Tenant` and `Product`.
- Namespace, folder, and class names must stay aligned.
- Route files should be named `api.php`.

## Current Areas and Modules

- `Core`: `Administrator`, `Auth`, `Authorization`, `Bootstrap`, `Client`,
  `Menu`, `Staff`, `Tenant`.
- `Commerce`: `Cart`, `Catalog`, `Purchase`, `Sale`.
- `Ticketing`: `Desfile`, `Event`, `FiestaFutbolInfantil`, `Ticket`.
- `Shared`: `Attachable`, `Forms`, `Integration`, `Logging`, `MailTest`,
  `Notification`, `StorageTest`, plus shared enums and rules.

## Notes For Future Changes

- New features should be added inside the corresponding domain first.
- Add new business features to the appropriate area under `app/Domains`.
- Keep generic reusable code in `app/Shared`; do not use it as a catch-all for
  business features.
- Avoid placing new business code in `app/Http/Controllers` or `app/Models`.