00 Explorable reference · Next.js 16 · React 19.2

A request dives down the layers,
then rides back up as fresh UI.

One form submission crosses the client boundary, an authenticating and validating Server Action, the server-only Data Access Layer, the ORM, and the database — then revalidatePath turns the trip around and a re-rendered Server Component streams new markup home. Press play, click any node for the framework mechanics, and toggle “what ships to the browser” to watch every server-only layer go dark.

01 The mental model

You describe the layers. The server enforces them.

Read   Server Component → DAL → ORM → DB   // no endpoint, no client JS
Write  Server Action    → DAL → ORM → DB   // authN + validate, then revalidate
HTTP   Route Handler    → DAL → ORM → DB   // the one public, external surface
Rule   dependencies point DOWN only — the DAL knows nothing about HTTP or rendering

02 The cast & their roles

Four pieces. Knowing who is allowed to do what explains the rest.

Mental models in one breath

03 Layers & the boundary

Every layer depends only on the one below it.

04 The runtime model · where the code physically runs

Your query never runs in the browser.

05 Choosing a primitive

Two questions pick the right entry point.

06 The security gate

A Server Action is a public endpoint wearing a function's clothes.

07 MVC, mapped

Same three responsibilities — a different vocabulary.

08 The whole slice

One vertical Post feature — every layer, once.

import { PrismaClient } from '@prisma/client';
const g = globalThis as unknown as { prisma?: PrismaClient };
export const db = g.prisma ?? new PrismaClient();
if (process.env.NODE_ENV !== 'production') g.prisma = db;

import 'server-only';
import { cache } from 'react';
import { db } from '@/lib/db';

// DTO: only the fields any caller is allowed to see.
export type PostDTO = { id: string; title: string; createdAt: Date };

export const getPublishedPosts = cache(async (): Promise<PostDTO[]> => {
  return db.post.findMany({
    where: { status: 'published' },
    orderBy: { createdAt: 'desc' },
    select: { id: true, title: true, createdAt: true }, // scrub the rest
  });
});

export async function createPost(input: { title: string; content: string; authorId: string }) {
  return db.post.create({ data: input, select: { id: true } });
}

'use server';
import { z } from 'zod';
import { revalidatePath } from 'next/cache';
import { getCurrentUser } from '@/lib/auth';
import { createPost } from '@/lib/dal/posts';

const NewPost = z.object({ title: z.string().min(1).max(200), content: z.string().min(1) });
export type ActionState = { error?: string } | { ok: true };

export async function addPost(_prev: ActionState, formData: FormData): Promise<ActionState> {
  const user = await getCurrentUser();            // authN — the action is public
  if (!user) return { error: 'You must be signed in.' };
  const parsed = NewPost.safeParse({             // validate — never trust the client
    title: formData.get('title'), content: formData.get('content'),
  });
  if (!parsed.success) return { error: 'Invalid input.' };
  await createPost({ ...parsed.data, authorId: user.id }); // delegate to the DAL
  revalidatePath('/posts');                       // refresh the cached read
  return { ok: true };
}

import { getPublishedPosts } from '@/lib/dal/posts';
import { NewPostForm } from './new-post-form';

export default async function PostsPage() {
  const posts = await getPublishedPosts();
  return (
    <main>
      <NewPostForm />
      <ul>{posts.map((p) => <li key={p.id}>{p.title}</li>)}</ul>
    </main>
  );
}

import { markPaid } from '@/lib/dal/posts';

export async function POST(request: Request) {
  const sig = request.headers.get('stripe-signature');
  const raw = await request.text();
  // verifyStripeSignature(raw, sig) ← Route Handlers have NO built-in CSRF/auth; you verify.
  const event = JSON.parse(raw);
  if (event.type === 'checkout.session.completed') await markPaid(event.data.object.metadata.postId);
  return Response.json({ received: true });
}