Golden flow
Purpose: show the exact ordered path of one request inside a single module (e.g. Ordering placing an order).
The compact “cycle” diagram often confuses readers by mixing descent and ascent. Below they are separated, then a sequence shows time order.
1. Request descent (inward)
| Step | Component | Responsibility | Must not |
|---|---|---|---|
| 1 | Controller | Pick Use Case, map input → DTO, map result → response | Contain eligibility / reservation / peer rules |
| 1 | Input validation | Validate format (types, required, max length) | Encode business policy |
| 2 | Application DTO | Typed carrier of UI input | Know ORM or HTTP transport details |
| 2 | Use Case | Orchestrate the feature (__invoke) | Call ORM directly, facades, or foreign *ModuleInterface |
| 3 | Entity / Domain service | Business meaning and invariants | Import host framework or other modules |
| 3 | Port interface | Declare I/O in Domain language | Mention ORM class names |
| 4 | Adapter | Talk to DB / peer / HTTP; map to Domain types | Leak ORM models back to the Use Case |
2. Response ascent (outward)
| Direction | Allowed types |
|---|---|
| Infrastructure → Application | Domain Entity, Domain DTO, scalars — never ORM models |
| Application → UI | Same Domain result (or a small Application result object) |
| UI → Client | Resource / array / response envelope only |
3. Full lifecycle sequence
Ordering “place order” mapping
| Sequence step | Concrete class (illustrative) |
|---|---|
| Validation | PlaceOrderRequest (or equivalent) |
| Application DTO | PlaceOrderDTO + line DTOs |
| Use Case | PlaceOrderUseCase |
| Nested helper | PrepareOrderLines (not called by UI) |
| Ports | OrderRepositoryInterface, WarehouseAvailabilityPortInterface |
| Adapters | Persistence repository, WarehouseAvailabilityAclAdapter |
Delivery wording
UI adapter (controller, request handler, admin action, console command) validates input shape, builds an Application DTO, invokes the Use Case, then maps the Domain result to a response.
Illustrative host mappings — not Core MUST
UI delivery (authorize → Application DTO → Use Case → present)
| Host | Typical place |
|---|---|
| Laravel | Controllers + Form Requests; optional Filament under `UI/Filament/` |
| Symfony | Controllers; API Platform as UI adapter if used |
| Yii | Controllers / actions as UI adapters |
| CodeIgniter | Controllers + validation as UI adapters |
| CakePHP | Controllers + Form helpers as UI adapters |
| Spiral | Controllers / prototypes as UI adapters |
| Slim | Route callables / Action classes (PSR-7/15) |
| Mezzio | PSR-15 request handlers / middleware |
Full topic pages: Adapters overview
Common mistakes
| Mistake | Fix |
|---|---|
| Controller calls repository / ORM directly | Controller → Use Case only |
| Use Case creates / queries ORM records directly | Inject OrderRepositoryInterface |
| Validation layer invokes Use Case | Controller invokes Use Case |
| Repository returns ORM models to Use Case | Map to Entity in Infrastructure |
| Peer module’s controller calls this Use Case | Peer uses ACL or Events only |
Checklist before merge
- One first-level Use Case is the only entry from UI for this action
- Application DTO is the only input type into
__invoke - All I/O goes through Domain ports
- No ORM types in Application / Domain
- Response mapping stays in UI
Next: use cases & DTOs · ports & persistence.