# App Structure

## Purpose

This document is the source of truth for where new application code belongs and which layer owns which responsibility.

## Layer ownership

### Controllers

Location:

- `app/Http/Controllers/**`

Rules:

- Controllers orchestrate only.
- Controllers may authorize, call services, and return views or redirects.
- Controllers must not contain business rules, payload mapping, or persistence-heavy logic.
- For warmup strategy and future refactors, controllers should prefer typed requests and DTO-backed services.

### Requests

Location:

- `app/Http/Requests/**`

Rules:

- Request classes own validation and request-shape normalization.
- Cross-field validation belongs here unless it requires domain state from multiple sources.
- New form features should add explicit request classes instead of validating raw `Illuminate\Http\Request` payloads in controllers.

### DTOs

Location:

- `app/Dto/**`

Rules:

- DTOs carry typed data between request, controller, and service layers.
- DTOs should not talk to the database.
- DTOs should avoid framework-heavy dependencies.

### Services

Location:

- `app/Services/**`

Rules:

- Services own business operations and write flows.
- Services may map product-facing fields into compatibility fields used by older internals.
- Services should return models, DTOs, or simple arrays with clear contracts.

### Models

Location:

- `app/Model/**`

Rules:

- Models own relations, scopes, casts, constants, and read-side helpers.
- Avoid putting full CRUD validation and write orchestration into models for new or refactored modules.
- Legacy modules may still use model-centric patterns, but new refactors should move toward Request + DTO + Service.

### Views

Location:

- `resources/views/**`

Rules:

- Use helper controls from `resources/views/helpers/form_control/**` for form fields when possible.
- Keep view-specific JavaScript inside the view partial only when the logic is tightly coupled to the rendered DOM.
- Prefer Bootstrap utility/layout classes first.
- Feature-specific CSS should be isolated with explicit prefixes in `public/core/css/app.css`.

### Translations

Location:

- `resources/lang/en/**`

Rules:

- New feature-local copy should use a dedicated translation file when the module is large enough.
- Warmup strategy uses `resources/lang/en/warmup.php`.

### Docs

Location:

- `docs/**`

Rules:

- Any task that changes UI, behavior, architecture, or API must update docs in the same task.
- Module docs should describe both behavior and code structure.
- Keep `CLAUDE.md`, module docs, and implementation consistent.

## Warmup strategy reference

Warmup strategy is the reference implementation for the stricter layering model:

- Requests: `app/Http/Requests/Admin/WarmupStrategy/**`
- DTOs: `app/Dto/WarmupStrategy*.php`
- Service: `app/Services/WarmupStrategyService.php`
- Model: `app/Model/WarmupStrategy.php`
- Views: `resources/views/admin/warmup_strategies/**`
- Translations: `resources/lang/en/warmup.php`
- Docs: `docs/warmup/**`