Render. Endpoint. Action.
Three entrypoints, one policy layer.

The mistake that makes App Router data access feel chaotic is collapsing two independent questions into one. Contract is the horizontal axis — which doorway: who is allowed to call it, what crosses the wire, who repaints afterward. Policy is the vertical axis — what the Data Access Layer enforces once you're inside: is there an actor, may they touch this row, which fields may leave, what must be atomic, what may be cached. They're orthogonal: every doorway still needs every policy concern. A Server Action isn't "safe" because it's not a public URL, and a Route Handler isn't automatically authorized because it has a nice 401 to return. Pick a cell — or flip to the layered view — to see how the two axes meet.

A Route Handler is an explicit HTTP resource. It lives in app/**/route.ts, exports functions named after HTTP methods — GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS — and speaks the Web Request/Response APIs. The URL is the API surface: anyone who can send an HTTP request to that route can call it, assuming your auth allows it.

A Server Action is not primarily a URL. It's a server function marked 'use server' that React/Next can invoke from a component interaction — <form action>, <button formAction>, or a client transition. The React interaction is the contract; the network plumbing underneath is framework-managed.

With a Route Handler you own the protocol — the URL, method, status code, headers, body shape, error format, cache headers and CORS behavior are yours to design. That's what makes it portable: a browser, a mobile app, a webhook provider, a curl command or another backend can all call the same endpoint.

With a Server Action you gain deep React/Next integration but lose a clean public HTTP contract. What crosses the wire is a framework-managed POST carrying a compiled action ID plus serialized arguments — and what comes back can include a fresh RSC Payload for the current route. Callable over the network, yes; a stable public API, no. Pick a doorway and replay its traffic.

A Route Handler is discovered by the filesystem router: app/api/orders/route.ts becomes the registered entrypoint /api/orders, and each exported method becomes a handler. Request in → your function → Response out. No React reference involved.

Server Actions are compiler-recognized. At build time, the compiler splits a 'use server' module in two: the server bundle keeps the real implementation, while the client bundle gets a reference — an action ID plus a dispatcher that knows how to POST back to Next. That's the "magic": you can import { updateUser } in a Client Component and call it like a local function, but what the browser actually got is a callable stub. Run the build below and watch the module split.

A Route Handler returns a normal HTTP response — status, headers, JSON — and then the caller decides what happens next: update local state? refetch a query? redirect? invalidate the TanStack Query cache? A Server Action can return a value and trigger a server re-render, sending a fresh RSC Payload back in the same response. Step through both mutation loops side by side and watch the roundtrip counters — this single difference is why Server Actions feel so "integrated" with the RSC tree, and why the TanStack loop trades an extra request for full client-side control.

This is where most confusion lives. All three doorways can call revalidatePath — but only a Server Action gets to ship the fresh UI back in the same response. A Route Handler that revalidates only marks the cache stale for the next visit; if you called it from a Client Component and want the current page to visibly update, you still need router.refresh() or queryClient.invalidateQueries() — TanStack's way of marking matching cached queries stale and refetching the active ones.

The default App Router read is a Server Component awaiting data directly — fetch, an ORM, or a database. Calling your own Route Handler from your own Server Component adds an HTTP hop inside your own server for nothing.

Route Handler security is familiar HTTP API security: validate the method, the session, the authorization, the body, the ownership; rate-limit; check CORS if browser-facing; return a safe response. Its big advantage is explicit HTTP failure modes — 401 403 404 422 429 500 — exactly what APIs and integrations want.

Server Actions feel like "just functions", and that feeling is the trap.

Prove it to yourself. The console below hosts a deleteOrder entrypoint — flip it between a Route Handler and a Server Action, toggle whether the code checks auth and ownership, then attack it from outside the UI.

Because a Server Component can await db.user.findMany() directly, every component, action and handler can become its own little backend — and that's exactly the problem. The security model scatters: each caller must independently remember to authenticate, authorize, scope by owner, select safe columns, avoid leaking secrets, handle errors, and shape a DTO. The bigger the app, the likelier one file forgets where: { ownerId: actor.id } or returns a raw row carrying passwordHash. Toggle the switch and watch the same six responsibilities either scatter across the tree or collapse into one shared layer.

The DAL isn't a Next.js feature, a required folder, or an ORM wrapper. It's an architectural boundary: the server-only layer that answers one question — who is allowed to touch the real data source, and what safe shape may leave? Next.js's own data-security guide recommends a dedicated DAL for new projects: server-only, authorization-checking, returning minimal DTOs.

A DAL guards two different boundaries that are easy to conflate. The module boundary keeps server code out of the client bundle: import 'server-only' is a build-time poison pill. The data boundary keeps sensitive values out of the HTML, the RSC Payload, action return values and Client Component props. The first is enforced by the compiler; the second only by discipline — explicit selects, explicit return types, and field-level authorization in the mapper.

It's not runtime magic and it doesn't "move" code anywhere. The package ships an export map that resolves to a throwing module in any client/browser compilation, so a client import fails the build:

The RSC Payload is not a private vault — anything a Server Component passes to a Client Component is serialized into it and visible in the network tab. Pass a raw row through and watch what a curious user finds. Flip to the DTO path to seal it.

Every entrypoint can be reached differently: a hidden button still accepts a POST, a page-level admin check doesn't protect an action defined elsewhere, and a proxy that checks auth doesn't authorize a specific row. CVE-2025-29927 made this concrete — affected Next.js versions could bypass authorization that lived in middleware. The lesson isn't "middleware is bad"; it's that middleware is a coarse gate and the DAL is the last line. Run the attack replay with auth in each position and watch which one holds.

If every DAL call re-checks the actor, won't that hammer the session store? No — React.cache() memoizes the lookup for the render pass, so a layout, page and three components asking "who is the actor?" run one query. Step the render tree and watch the counter. Then trip the footgun: pass a fresh object as an argument and the reference-keyed cache misses.

The biggest real-world smell is one data/*.ts file that imports redirect, cookies, revalidatePath and runs SQL — tangling routing, HTTP, cache and data authorization into a knot that no other caller can reuse. The rule: navigation, cookies, cache invalidation and HTTP responses belong to the entrypoint; SQL, authorization, transactions, DTOs and invariants belong to the DAL. Sort each concern into its layer — the widget will tell you if you're building a tangle.

Why it matters: the moment your DAL calls redirect('/login'), it can no longer be reused by a Route Handler that wants a 401, a webhook with no browser to redirect, a CLI script, or a test that wants a typed error. The DAL should throw domain outcomes — UnauthorizedError, NotFoundError, ValidationError — and let each entrypoint translate them into redirect(), notFound(), or Response.json(…, { status }).

An action that calls createOrder(), then decrementStock(), then createPayment() in sequence has no answer to "what if step 2 fails after step 1 committed?" The rule: a single use-case DAL function owns the transaction; the Server Action stays thin. Step the checkout with a failure injected at each stage — watch the difference between a db.$transaction that rolls back cleanly and three loose writes that corrupt state.

Payment providers retry, so your endpoint may see the same event twice. The idempotency check belongs inside the same transaction — but a naïve findFirst-then-create is a check-then-act race two concurrent retries can both pass. The robust version leans on a unique DB constraint and catches the violation.

App Router caching confuses people because there are several caches with different lifetimes, and this section stitches together two altitudes: the entrypoint question from §06 — who marks it stale and who sees it fresh — and the data-layer question — which of the three caches a DAL touches. Switch between them, then read the decision table.

This is where the DAL stops being architecture and becomes systems. A database connection in a Node runtime is a real TCP socket holding a real file descriptor, backed by a real server-side process and a slot in the database's connection limit. The DAL is where you keep that resource sane: a client singleton that survives dev HMR, pool math that doesn't detonate under serverless concurrency, and awareness that the Edge runtime can't open a TCP socket at all. Inspect the pool to see the resource chain.

Server Component fetch is the best default read path — render the route with the data already in it. Route Handlers are the best network boundary — when the request is naturally an API call. Server Actions are the best mutation-to-UI path — when a user action changes server state and the current screen should reflect it. And TanStack Query is the best client-owned lifecycle — when loading states, refetching, polling and invalidation belong to the component.

The clean default architecture: reads flow through Server Components, UI writes through Server Actions, external HTTP access through Route Handlers — and all three call the same Data Access Layer. The DAL isn't a Next.js file convention; it's an architecture pattern — import 'server-only', auth-aware, DTO-shaped — and it's what prevents the same query and auth logic from being duplicated across page.tsx, actions.ts and route.ts.

Same business logic, different entrypoints. Flip through the four files:

Every doorway has a failure mode. Server Component fetch becomes wrong when data must update repeatedly without navigation, or other clients need the resource. A Route Handler becomes wrong when only your own Server Component calls it. A Server Action becomes wrong when the consumer isn't React UI, when you need CORS, raw webhook bodies, files or streams — or when you're tempted to use actions as a general RPC layer. Pick a scenario; the detector names the right door and shows the shape.

Every axis from the deep comparison, in one reference sheet. Hover a row; scroll sideways on small screens.

The same checks, in the order that resolves fastest: render-need first, UI-mutation second, URL-need third, client-lifecycle last. Walk it for the feature you're building right now.

Yes, there are more than three. The doorways above are the entrypoints; these are the concrete fetching techniques that flow through them — including the newer promise-over-the-boundary trick and the two build-time fetchers that are not general data layers.

For a serious Next.js app, the structure falls straight out of the doorways. Add the api/ folder only when a real HTTP consumer exists; add TanStack Query only when a Client Component genuinely owns an async lifecycle.

And the shorthand rule, doorway by doorway: