Handbook

Platform architecture

How Laravel, tenancy, Payload, and the Next apps divide responsibility.

Three planes

Central plane: platform database, tenant registry, billing, and cross-tenant administration. Laravel remains the primary API and integration backbone.

Tenant plane: isolated database per workspace. Tenant API controllers and modules operate only after tenancy middleware establishes context.

Public plane: payload-web serves marketing, auth-adjacent flows, and central admin UI on dedicated routes. It is not a substitute for tenant business APIs.

Next.js surfaces

work-web (station) and backoffice-web carry the long-term tenant UX. They call Laravel JSON endpoints and share contracts from packages/platform-contracts.

payload-web owns CMS-backed pages, preview, and operator-visible central tools that belong on the public host.

Same-host deployments typically reverse-proxy path prefixes to PM2 processes on ports 3010, 3020, and 3040.

Modules and boundaries

Prefer app/Modules for new domain behavior: declare dependencies, use hooks, and avoid silent edits to unrelated core controllers.

Communication features must respect tenant credits and policy helpers—never send paid channels from tenant context without checks.