shopit-back/AGENTS.md

Project Conventions

Architecture

This project uses a domain-oriented structure under app/Domains.

Each domain must live in:

app/Domains/<DomainName>/

Supported folders inside each domain:

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:

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.