Confused by Next.js backend structure? Discover three battle-tested patterns for organizing your server-side logic, from quick API routes to scalable, decoupled services, and stop writing messy, unmaintainable code.

So, You’re a Senior Dev. How Do You Actually Structure Backend Logic in Next.js?

I remember the moment I almost lost my mind on the “Hydra” project. It was a marketing CMS, and a junior dev, bless his heart, had built the initial API. The problem? Every single API route in the /pages/api directory was a 500-line behemoth. It directly instantiated the database client, had raw SQL queries as strings, handled validation, and managed session logic… all in one giant function. When the CISO came knocking because our session tokens weren’t being invalidated properly on logout, we had to fix it in 12 different files. That was the day I mandated a structure. That chaos is why we’re having this chat.

The Root of the Problem: Freedom is a Trap

Let’s be honest. Next.js is incredible, but it gives you just enough rope to hang yourself. It says, “Here are API routes. Go wild.” For someone coming from a structured backend framework like Rails, Django, or NestJS, this is jarring. There are no built-in conventions for services, models, or data access layers. This flexibility is a feature, but without discipline, it leads directly to the Hydra project I just described: a multi-headed monster of duplicated logic and maintenance nightmares.

So, how do we, the folks in the trenches, impose order on this chaos? After building dozens of these systems, I’ve found it boils down to three patterns. Let’s break them down.

Approach 1: The “Happy Path” (Co-located Logic)

This is the default, the one you see in all the tutorials. You put your logic directly inside the API route handler file. It’s fast, it’s simple, and for a small project, it’s perfectly fine.

Imagine a simple “get post by ID” endpoint. The file structure is minimal:

src/
└── pages/
    └── api/
        └── posts/
            └── [id].ts

And the code inside [id].ts might look like this:

import { PrismaClient } from '@prisma/client';
import type { NextApiRequest, NextApiResponse } from 'next';

const prisma = new PrismaClient(); // Uh oh, instantiating this everywhere is a bad sign.

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { id } = req.query;

  if (req.method !== 'GET') {
    res.setHeader('Allow', ['GET']);
    return res.status(405).end(`Method ${req.method} Not Allowed`);
  }

  try {
    const post = await prisma.post.findUnique({
      where: { id: String(id) },
    });

    if (!post) {
      return res.status(404).json({ message: 'Post not found' });
    }

    return res.status(200).json(post);
  } catch (error) {
    console.error('Failed to fetch post:', error);
    return res.status(500).json({ message: 'Internal Server Error' });
  }
}

When to use this: Prototyping, small personal projects, or single-purpose serverless functions where the logic will never, ever be shared. Think a simple contact form submission.

Warning: This pattern falls apart the second you need to reuse any of that logic. What if you need to get a post by its ID for an internal admin task? You either duplicate the code or start a messy refactor. This is how the Hydra begins.

Approach 2: The “Scalable Standard” (The Service Layer)

This is my default for any serious project. We treat the Next.js API routes as a thin Controller layer. Their only job is to handle the HTTP request/response cycle, parse the request, and call a dedicated “service” to do the actual work. All the business logic, database interaction, and validation live in a separate, well-organized directory.

Here’s the structure I enforce on my teams:

src/
├── app/ (or pages/)
│   └── api/
│       └── posts/
│           └── [id]/
│               └── route.ts  // The thin controller
├── lib/
│   └── db.ts             // Singleton Prisma Client instance
└── server/
    ├── services/
    │   └── post.service.ts // All business logic for posts lives here
    ├── models/
    │   └── (schemas, types, etc. e.g. Zod schemas)
    └── utils/
        └── session.ts      // e.g. Helpers to get current user

Now, our API route (route.ts) becomes incredibly simple and readable:

// File: src/app/api/posts/[id]/route.ts
import { getPostById } from '@/server/services/post.service';
import { NextResponse } from 'next/server';

export async function GET(request: Request, { params }: { params: { id: string } }) {
  try {
    const post = await getPostById(params.id);
    if (!post) {
      return NextResponse.json({ message: 'Post not found' }, { status: 404 });
    }
    return NextResponse.json(post);
  } catch (error) {
    console.error(`Error fetching post ${params.id}:`, error);
    return NextResponse.json({ message: 'Internal Server Error' }, { status: 500 });
  }
}

And the real work happens in the service layer:

// File: src/server/services/post.service.ts
import { prisma } from '@/lib/db'; // Import the singleton instance!

export async function getPostById(id: string) {
  // Here you can add more complex logic:
  // - Check user permissions
  // - Join related data
  // - Sanitize output
  console.log(`Fetching post from prod-db-01 for ID: ${id}`);
  const post = await prisma.post.findUnique({
    where: { id },
    include: { author: true }, // Example of business logic: always include the author
  });
  return post;
}

export async function updatePost(...) {
  // ... more reusable logic
}

When to use this: 95% of the time. This is the sweet spot for building robust, maintainable, and testable CRUD/CMS applications within the Next.js ecosystem.

Approach 3: The “Nuclear Option” (A Decoupled Backend)

Sometimes, your backend needs are so complex that trying to shoehorn them into the serverless model of Next.js/Vercel is a fool’s errand. Think long-running background jobs, websockets, complex microservice orchestration, or heavy computational tasks.

In this scenario, we treat Next.js as what it excels at: a best-in-class React frontend framework. The backend is a completely separate application (e.g., a Node.js/Express server, a Go API, etc.) running on its own infrastructure (like a container on AWS Fargate or a VM).

The Next.js app then communicates with this backend via standard REST or GraphQL APIs, just like it would with any third-party service.

When to use this:

• Your app requires real-time features like chat (WebSockets).
• You have heavy background processing (video encoding, report generation).
• You have a dedicated backend team that works independently of the frontend team.
• Your authentication and authorization model is extremely complex and doesn’t fit neatly into the Vercel request lifecycle.

Pro Tip: Don’t jump to this just because your app is “big”. The service layer pattern (Approach 2) can handle very large applications. Only go nuclear when you have a specific technical requirement that the Next.js serverless environment fundamentally cannot support well. It adds operational complexity and cost.

My Final Take: A Quick Comparison

There’s no single right answer, only the right answer for your project’s scale and complexity. Here’s how I decide:

Stop building Hydras. Start with the Service Layer pattern. Your future self—and the poor soul who inherits your code at 2 AM during a production outage—will thank you.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions