Backend Option A: Node.js API with Route Handlers

What you'll build

A backend in the same project as your frontend from Part 1 — a small Notes API (list, create, delete) using Next.js Route Handlers. One codebase, one deploy: the fullstack-JS path.

The idea: Route Handlers are your backend

Any folder under app/ with a route.ts (instead of page.tsx) is a backend endpoint. Export functions named after HTTP methods — GET, POST, DELETE — that run on the server.

The project structure

Start with the minimum, then let it grow into the shape below — one concern per file in lib/, and routes that stay thin:

my-app/
├─ app/
│  ├─ notes/page.tsx                  # the UI            →  /notes
│  └─ api/
│     ├─ notes/route.ts               # GET + POST        →  /api/notes
│     ├─ notes/[id]/route.ts          # DELETE            →  /api/notes/:id
│     └─ webhooks/stripe/route.ts     # inbound webhook (public, signed)
├─ lib/
│  ├─ db.ts                           # data layer — the ONLY place that touches the DB
│  ├─ auth.ts                         # resolve { userId, orgId } from the session
│  └─ schemas.ts                      # Zod request/response validation
├─ middleware.ts                      # coarse "are you logged in?" gate at the edge
└─ .env.local                         # secrets (gitignored) — never commit

Your first Route Handler

// app/api/notes/route.ts
import { NextResponse } from 'next/server';
import { listNotes, createNote } from '@/lib/db';

export async function GET() {
  return NextResponse.json(await listNotes());
}

export async function POST(req: Request) {
  const { text } = await req.json();
  if (!text) return NextResponse.json({ error: 'text required' }, { status: 400 });
  return NextResponse.json(await createNote(text), { status: 201 });
}

A data layer

Keep data access in one module so handlers stay clean. Start in-memory, then swap in a real DB:

// lib/db.ts  — start simple (resets on restart)
type Note = { id: string; text: string };
let notes: Note[] = [];
export async function listNotes() { return notes; }
export async function createNote(text: string) {
  const note = { id: crypto.randomUUID(), text };
  notes.push(note); return note;
}
export async function deleteNote(id: string) { notes = notes.filter((n) => n.id !== id); }

Call it from the client

const notes = await (await fetch('/api/notes')).json();

await fetch('/api/notes', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ text: 'Buy milk' }),
});

Dynamic routes for delete

// app/api/notes/[id]/route.ts
import { NextResponse } from 'next/server';
import { deleteNote } from '@/lib/db';

export async function DELETE(_req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  await deleteNote(id);
  return new NextResponse(null, { status: 204 });
}

Validation & errors

Never trust the request body. Validate (a library like Zod helps) and return a clear status code:

try {
  const data = schema.parse(await req.json());  // throws on bad input
} catch {
  return NextResponse.json({ error: 'invalid body' }, { status: 400 });
}

The database connection

The in-memory array is fine for a demo; a real app needs a database — and serverless Next.js hits the same trap AWS Lambda does: every serverless invocation can open its own connection, and Postgres has a hard limit. Two rules keep you safe — reuse one client, and go through a pooler.

Reuse one client — don't reconnect per request

Cache the client on globalThis so dev hot-reloads and warm invocations reuse a single instance instead of leaking a new connection every time:

// lib/db.ts — one pooled client, cached across reloads/invocations
import { Pool } from 'pg';

const g = globalThis as unknown as { pool?: Pool };
export const pool =
  g.pool ?? new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
if (process.env.NODE_ENV !== 'production') g.pool = pool;   // survive HMR in dev

export async function listNotes(orgId: string) {
  const { rows } = await pool.query(
    'select id, text from notes where org_id = $1', [orgId]);
  return rows;
}

Secrets & environment variables

Your DATABASE_URL and API keys are secrets. In Next.js the make-or-break rule is the server/client boundary: anything that reaches a component in the browser is public.

# .env.local  (gitignored — never commit)
DATABASE_URL=postgres://…            # server-only: stays on the server
STRIPE_SECRET_KEY=sk_live_…          # server-only
NEXT_PUBLIC_SITE_URL=https://…       # NEXT_PUBLIC_ = shipped to the browser!

• process.env.X is server-only by default — read it in Route Handlers, Server Components, and lib/. It never enters the client bundle.
• NEXT_PUBLIC_ is inlined into the browser bundle — only for genuinely public values (a site URL, a publishable key). Put a secret behind that prefix and you've shipped it to every visitor.
• Source of truth is your platform — set the same vars in Vercel (Project → Settings → Environment Variables), scoped per environment: Development, Preview, Production.

vercel env pull .env.local              # pull the project's env into your local file
vercel env add DATABASE_URL production  # add / rotate a secret in the platform

The request's user & organization context

A real API is multi-tenant: every request belongs to a signed-in user in an organization, and one org must never see another's data. Don't read the identity from the body or a query param — resolve it from the session on the server, and scope every query by orgId.

// lib/auth.ts — resolve identity from the session cookie (server-side)
import { cookies } from 'next/headers';
import { createServerClient } from '@supabase/ssr';

export async function requireContext() {
  const supabase = createServerClient(url, key, { cookies: cookies() });
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) throw new Response('Unauthorized', { status: 401 });
  return { userId: user.id, orgId: user.app_metadata.org_id as string };
}

// app/api/notes/route.ts — resolve context, then scope the query
export async function GET() {
  const { orgId } = await requireContext();
  return NextResponse.json(await listNotes(orgId));   // lib/db filters by org_id
}

Background work & webhooks

A Route Handler's job is to answer the request. Slow follow-up work — sending an email, reindexing, calling a third party — shouldn't make the caller wait, and events arriving from other systems need a public endpoint.

Do the slow work after the response

Next.js after() runs a callback after the response is sent — fire-and-forget for non-critical tasks, off the caller's critical path:

// app/api/notes/route.ts
import { after } from 'next/server';

export async function POST(req: Request) {
  const { orgId } = await requireContext();
  const note = await createNote(orgId, (await req.json()).text);   // commit first
  after(() => sendDigestEmail(orgId));      // runs AFTER the 201 is returned
  return NextResponse.json(note, { status: 201 });
}

Receive webhooks

An inbound webhook (Stripe, Resend, GitHub) is just a POST route — but it's called by a machine with no session cookie, so it's public and signature-verified, not session-authed:

// app/api/webhooks/stripe/route.ts — public route; verify the signature
export async function POST(req: Request) {
  const body = await req.text();                    // RAW body for the signature
  const sig = req.headers.get('stripe-signature')!;
  let event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new NextResponse('bad signature', { status: 400 });
  }
  after(() => handle(event));               // 200 fast; do the work off the path
  return NextResponse.json({ received: true });
}

A CLAUDE.md for a fullstack app

Pin down the API conventions so new endpoints stay consistent:

# CLAUDE.md

## What this is
Fullstack Next.js app (App Router). UI in app/, backend in app/api/** (Route Handlers).

## Structure  # one concern per file in lib/; routes stay thin
app/
  notes/page.tsx                 # UI
  api/notes/route.ts             # GET + POST
  api/notes/[id]/route.ts        # DELETE
  api/webhooks/*/route.ts        # public, signature-verified
lib/
  db.ts                          # data access — the ONLY place that touches the DB
  auth.ts                        # resolve { userId, orgId } from the session
  schemas.ts                     # Zod request/response validation
middleware.ts   # coarse auth gate   ·   .env.local   # secrets (gitignored)

## Commands
- Dev / Build / Lint: npm run dev / build / lint

## Backend conventions
- Endpoints: app/api/<name>/route.ts (export GET/POST/DELETE). Dynamic: [id]/route.ts.
- Routes are thin: parse → resolve context → validate → delegate to lib/. No DB in routes.
- ALL data access goes through lib/db.ts. Validate every body with Zod → proper status codes.

## Auth & multi-tenancy
- Resolve { userId, orgId } from the SESSION (lib/auth.ts), never from the body/query.
- Scope every query by orgId in lib/db.ts — no route may leak another tenant's data.

## Database
- One pooled client cached on globalThis; small max; connect via a pooler (Supabase/Neon/PgBouncer).
- Migrations run in CI before the deploy.

## Secrets & env
- Secrets live in .env.local (gitignored) + the platform env (Vercel), per environment. Never commit.
- process.env.X is server-only; NEXT_PUBLIC_ ships to the browser — never a secret.

## Background & webhooks
- Slow work: after() (best-effort) or a queue (QStash/Inngest) for durable, retried jobs.
- Webhooks: public route, verify the provider signature on the raw body, be idempotent.

## Verify
npm run lint, then curl the endpoints (or drive the UI) before saying done.

Let Claude Code build the endpoints

> Add a Notes feature: a lib/db.ts data layer, a GET+POST route
  handler at app/api/notes, a DELETE at app/api/notes/[id], and a
  /notes page that lists notes with a form to add and a delete
  button. Validate input and handle errors.

Adding the next resource — same shape

The point of the layering is that the second resource, and the twentieth, is added the same way as the first. To add orders next to notes you touch the same layers — and nothing existing changes:

// new files only — notes/* is untouched
app/api/orders/route.ts        // endpoints — thin; reuse requireContext()
app/api/orders/[id]/route.ts   // dynamic route
lib/orders.ts                  // data access for orders — org-scoped queries
lib/schemas.ts                 // + OrderCreate / OrderResponse (Zod)

• Endpoints only under app/api/<name>/route.ts — thin: parse, resolve context, validate, delegate. No logic in the route.
• Data access in a lib/ module — never in the route; every query scoped by orgId.
• One Zod schema per input/output, and reuse the shared session + DB helpers — don't re-auth or reconnect.
• Nothing existing changes — a new resource is new files, not edits to notes.

Ask for a feature the way an engineer would

Once the API exists, don't just say "add search." The best prompts state the contract, respect your layers, pin down validation and status codes, protect what already works, and end with a way to verify:

> Add tag filtering to the Notes API.
  Contract: GET /api/notes?tag=work returns only notes with that
  tag; no tag param returns all notes.
  Keep the layers separate — put the query logic in lib/db.ts as
  getNotes({ tag }); the route handler only parses the query param
  and calls it.
  Validate: tag must be a non-empty string when present — return
  400 on bad input, 200 with a JSON array otherwise.
  Don't change the existing GET/POST behavior or response shape.
  Then give me a curl command for each case so I can verify.

• Contract first — exact route, query params, and response shape leave no room to guess.
• Name the layers — "query logic in lib/db.ts, handler stays thin" keeps the code clean instead of piling logic into the route.
• Validation & status codes — say what's valid and which code each case returns (400 vs 200).
• Guard existing behavior — "don't change GET/POST" stops a new feature from quietly breaking an old one.
• End with verification — ask for curl commands (or a test) so you confirm it, not just the model.

Say how the frontend should show the data

An endpoint that returns JSON is only half the job — tell Claude Code how the data should look on screen. Name the views you want and point them at the API you already have:

> Add a /notes/dashboard page that visualizes the Notes data:
  - Three stat cards on top: total notes, number of tags, and
    notes added this week.
  - A bar chart of notes-per-tag (use Recharts).
  - A sortable table of the most recent notes below.
  Fetch from the existing GET /api/notes. If you need an aggregate
  (counts per tag), add GET /api/notes/stats and keep the counting
  logic in lib/db.ts — don't compute it in the component.
  Match the app's dark theme and make it work on a phone.
  Show placeholders while it loads and an empty state at zero notes.

• Name the views — "stat cards, a bar chart, a sortable table" is far clearer than "show the data nicely."
• Pick the chart library — say Recharts (or Tremor) so you don't get a random one.
• Reuse the API, or add a clean aggregate — let the server do the counting in lib/db.ts; keep the component about display, not math.
• Ask for the states — loading placeholders and an empty state are what separates a demo from a real UI.
• Theme & responsive — "match the dark theme, work on a phone" stops it from looking bolted on.

Deploy