tRPC and backend reference

packages/cloud appRouter, procedures vs server actions, and pointers to Payload-backed backend code.

Written By Zoro

Last updated 3 days ago

tRPC in this monorepo

tRPC in this monorepo provides typed RPC endpoints consumed from React clients (often with React Query). It complements Next.js Server Actions, which handle many tenant-scoped mutations and cache revalidation. The internal decision guide lives in .cursor/rules/platform/trpc-vs-actions.mdc (summarised below).

Layout

PathPurpose
packages/cloud/src/trpc/index.tsinitTRPC, publicProcedure, userProcedure (authenticated), context, superjson.
packages/cloud/src/trpc/routers/index.tsappRouter composition and AppRouter type export.
packages/cloud/src/trpc/routers/*Domain routers (stripe, subscriptions, user, …).
apps/dashboard/.../api/trpc/[trpc]/route.tsHTTP adapter for the dashboard app.

appRouter namespaces (authoritative list)

Registered keys on appRouter (from routers/index.ts):

auth, user, secrets, vpsPlans, vpsOrders, card, stripe, orders, discord, rewards, cloud, templates, banners, siteSettings, authConfig, coupons, terms, subscriptions, branding, workerNodes.

Client calls use dotted paths such as stripe.createSetupIntent or subscriptions.getPlans.

Procedures

KindWhen it runsTypical use in dFlow
publicProcedureNo session requiredPublic plan catalog, marketing data, auth config.
userProcedureRequires Payload authBilling, profile, purchases, signed-in settings.

Errors use TRPCError with HTTP-friendly codes where configured.

Server Actions vs tRPC (short)

  • Prefer Server Actions for form posts, tenant-scoped mutations, revalidatePath, and simple Payload CRUD from the dashboard.
  • Prefer tRPC for React Query-driven reads, pagination/filter shapes, public endpoints used from marketing surfaces, and some Stripe flows that fit mutation/query composition.

This is a maintainer split; customers interact through the UI, not by choosing transport.

Payload and the rest of the backend

Business data lives in Payload CMS collections. Server Actions and tRPC procedures call payload.find, payload.create, payload.update, and related APIs. Collection names (for example services, applications, projects) appear throughout packages/core.

Learn more