Backend Guide

Use this page for Core-specific backend conventions. Standard Laravel rules (Eloquent, Form Requests, Policies, API Resources, queues, config(), types, Pint, PHPUnit) are in the always-loaded AGENTS.md. Use backend-guidelines skill for task execution.

Architecture Fit

Start with ../ARCHITECTURE.md to locate the route surface, request pipeline, processor layer, async path, and persistence boundary.

Controllers should stay thin:

1. route middleware authenticates and authorizes the boundary;
2. validated input via Form Requests or Spatie Data DTOs injected on the controller (see backend-guidelines — Spatie Data DTOs for Management Hub UI POST routes);
3. controllers call actions or services;
4. API Resources or response objects shape output;
5. queued jobs handle long-running work (scheduled commands should dispatch jobs, not run heavy logic inline).

Management Hub APIResponse endpoints must return proper HTTP status codes on failure (400/500, not 200 with success: false); see backend-guidelines — Management Hub API responses.

Hub Authorization

Management Hub routes and V2/shared hub routes do not have identical authorization assumptions. Check sibling routes in the same route file before copying middleware from another hub. Keep hub-specific authorization aligned across route, policy, UI, and tests.

Entrust permission strings on Management Hub routes use the permission: middleware, not Laravel can: (see backend-guidelines).

For Management Hub brand detail edit actions, align backend authorization with the frontend canUserEditBrandDetails gate unless product explicitly changes access.

See Also

• docs/backend/testing.md — PHPUnit authoring conventions and suite commands.
• docs/backend/linting-and-formatting.md — Pint IDE setup.
• test-strategy skill — decision tree for choosing which tests to run.