# 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 under `app/Domains`.

Each domain must live in:

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

Supported folders inside each domain:

```text
app/Domains/<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 domain defines its own routes in `app/Domains/<DomainName>/routes/api.php`.

## Namespaces

Use this namespace pattern:

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

## 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 Domains

- `Tenant`
- `Product`

## Notes For Future Changes

- New features should be added inside the corresponding domain first.
- If a concern does not belong to an existing domain, create a new domain under `app/Domains`.
- Avoid placing new business code in `app/Http/Controllers` or `app/Models`.