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:

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:

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:

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.

3.6 KiB Raw Blame History