crud

CRUD

A CRUD feature is a stack, not a single file. The route declares one router.resource(...) scoped by auth middleware; the controller has 5–7 tiny methods that only orchestrate; each mutation has a VineJS validator; a BasePolicy gates every method; each write goes through a single-purpose action class; a transformer produces per-page shape variants; the read side lives in queries/; the UI is Inertia pages under <mod>/ui/pages/. The point is that no single layer holds more than its own responsibility, and adding the next resource is copy-shape, not think-shape.

Rules

Every HTTP method — including index — follows the same 3-step spine:

1. Authorize via bouncer.with(XPolicy).authorize(...). A where('owner_id', user.id) clause in the query is not a substitute — the policy is the source of truth.
2. Validate via request.validateUsing(...).
3. Render / redirect — either inertia.render('...', props) for reads or response.redirect().back() / .toRoute(...) for writes. Writes call an action in between.

Authentication is the middleware's job — controllers never call authenticate(); use auth.getUserOrFail() when the handler needs the user. Anything past .authorize() that also does an owner check is redundant; anything before it that touches the DB other than loading the resource being authorized is a leak.

Layer conventions

• Route — router.resource('/entities', EntitiesController).only([...]). Guard by wrapping in a router.group(() => {...}).middleware(middleware.auth()) block (see [[routes]]). Custom verbs go as separate router.post(...) calls, not extra controller methods.
• Controller (thin) — one method per resource action. Body order: policy → validator → action call → render/redirect. No business logic, no queries longer than one line, no ORM calls beyond Model.findOrFail.
• Validator — VineJS vine.create({...}) per mutation, exported from <mod>/validators/<entity>.ts (one file per entity — validators/users.ts, validators/tokens.ts). Use vine.withMetaData<{...}>().create({...}) when a rule depends on route params (e.g. unique-except-self on edit). vine.compile() is deprecated — use vine.create().
• Policy — BasePolicy subclass at <mod>/policies/<entity>_policy.ts. One method per gated action. Return boolean | AuthorizerResponse. Gate before validating: await bouncer.with(XPolicy).authorize('action', resource?). See [[authorization]].
• Action — one class per write in <mod>/actions/<verb_entity>.ts. Input is a plain interface; the class has one async handle(input) method. Never takes HttpContext. Side effects go through domain events — see [[actions-events]].
• Transformer — BaseTransformer<Model> with toObject() as the base + variants (forList, forEdit, forSharedProps, forProfile). Call Transformer.transform(model).useVariant('forEdit') or Transformer.paginate(rows, meta).useVariant('forList'). Never send raw Lucid instances to Inertia — the shape leaks and the response type drifts.
• Query — read-only, <mod>/queries/list_<entities>.ts. Full patterns (list queries + read models for aggregate screens) live in [[queries]].
• Inertia pages — under <mod>/ui/pages/<entity>/. Index is a full page; create/edit are modals mounted over the index. See [[inertia]].