pn-backend-scaffolding

Backend scaffolding

When to use

• Adding a new API route, handler, or endpoint.
• Creating a new backend module, service, or domain.
• Setting up a new Node backend project from scratch.
• Adding a new resource to an existing API.

Folder structure

Prefer domain-driven layout over technical-layer layout:

# Domain-driven (preferred)
src/
  users/
    users.router.ts     # Express/Fastify route definitions
    users.service.ts    # Business logic
    users.schema.ts     # Zod validation schemas
    users.types.ts      # TypeScript types for this domain
  orders/
    orders.router.ts
    orders.service.ts
    orders.schema.ts
  shared/
    db.ts               # DB connection/pool
    errors.ts           # AppError class, error codes
    middleware/
      authenticate.ts
      errorHandler.ts
  index.ts              # App entry point

vs. technical-layer (avoid for anything beyond a toy project):

# Avoid at scale
controllers/
models/
routes/
services/

Express scaffold

// src/users/users.router.ts
import { Router } from "express";
import { authenticate } from "../shared/middleware/authenticate.js";
import { asyncHandler } from "../shared/middleware/asyncHandler.js";
import { CreateUserSchema } from "./users.schema.js";
import { createUser, getUserById } from "./users.service.js";

export const usersRouter = Router();

usersRouter.post(
  "/",
  authenticate,
  asyncHandler(async (req, res) => {
    const body = CreateUserSchema.parse(req.body); // throws on validation fail
    const user = await createUser(body);
    res.status(201).json({ data: user });
  })
);

usersRouter.get(
  "/:id",
  authenticate,
  asyncHandler(async (req, res) => {
    const user = await getUserById(Number(req.params.id), req.user.id);
    res.json({ data: user });
  })
);

// src/shared/middleware/asyncHandler.ts
import type { Request, Response, NextFunction, RequestHandler } from "express";

export function asyncHandler(
  fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>
): RequestHandler {
  return (req, res, next) => fn(req, res, next).catch(next);
}