Node.js backend best practices: structure, errors, and production

The business impact isn't abstract. One client in Dubai lost a day's worth of payment webhooks because errors weren't being logged anywhere. Another in Kuwait had their app degrade into timeout hell because the database connection pool was configured for toy traffic. Here's what separates projects that survive production from projects that don't: it's not React vs Vue, or whether you use TypeScript. It's the structure you chose in month one, the error boundaries you built in, and how you handle resources before they fail.

Most Node.js projects start the same way. You create an app.js file. You start jamming code into it. Middleware goes here. Routes go there. Database logic sits next to API handlers. It works for a week. Then you add a second developer and suddenly nobody can find anything. Add a third and your git merges become a nightmare. Add logging—or worse, error handling—and your 500-line app becomes 2000 lines of spaghetti where a change in one place breaks something in three others.

I'm not exaggerating. The most expensive projects I've helped salvage started exactly here: not because the code was fundamentally broken, but because it was impossible to reason about. You couldn't test the business logic without spinning up a database. You couldn't add logging without touching every file. You couldn't swap out the email provider without grep-and-replacing your entire codebase.

Folder structure isn't about philosophy or elegance. It's about making it possible for you—or a team of you—to change things without everything breaking. It's about being able to write tests. It's about knowing where the logging happens and where errors get swallowed. It's about being able to understand what the app does at 3 AM when something breaks.

The folder structure that survives scale

Here's what a production-ready Node.js structure looks like. Not the only way—but a way that works for startups, scaleups, and agencies serving clients across the Gulf:

src/
  middleware/
    auth.js
    errorHandler.js
    requestLogger.js
  routes/
    auth.js
    users.js
    payments.js
  controllers/
    authController.js
    userController.js
    paymentController.js
  services/
    authService.js
    userService.js
    emailService.js
    paymentService.js
  models/
    User.js
    Transaction.js
  utils/
    logger.js
    database.js
    validators.js
  config/
    database.js
    email.js
    constants.js
tests/
  unit/
  integration/
  fixtures/
logs/
.env
.env.example

Routes are a thin layer that receive requests, validate input, and pass to controllers. Controllers orchestrate the business logic by calling services. Services are where your actual business happens—user authentication, email sending, payment processing. Models are database interactions, completely separated from logic. Middleware is where cross-cutting concerns live: logging, authentication checks, error catching.

When you organize this way, you can test a service without touching a route. You can swap out your email provider by changing one service. You can add logging to every request in one place. When something breaks, you know which layer failed.

The separation doesn't have to be dogmatic. Small projects might combine controllers and services. But the principle holds: if you're testing business logic, you shouldn't need a web server running. If you're adding a feature, you shouldn't be grep-and-replacing across fifteen files.

Most teams in Kuwait who ship custom software to clients use something like this structure. Not because it's perfect, but because it's the minimum structure that survives having more than one person work on it, and more than one change happen at once.

Error handling: what most teams get wrong

Here's what happens in projects I've inherited: errors occur, they get caught somewhere (or they don't), and then nothing. No log. No alert. No trail. The request returns 500, the user refreshes, and nobody—not your team, not your monitoring, not the client—knows it happened.

The reason is almost always the same: error handling was bolted on as an afterthought. Someone wrapped a function in try-catch and called it done. Or middleware swallows exceptions silently. Or you're logging to stdout instead of a file, and nobody ever looks at stdout. I've seen more production outages caused by where errors were hidden than by what the errors actually were.

Here's what production-ready error handling looks like:

Errors get logged consistently. Every error goes to a logger (not console.log), with context: the request ID, the user, the timestamp, the stack trace. Not just the message. When something breaks, you know what broke and where.

Unhandled rejections don't disappear. You listen for unhandledRejection and log it. A promise got rejected somewhere and nobody was waiting for it? You know about it immediately.

Errors propagate upward, not sideways. A service throws. The controller catches it (or doesn't). The error handler middleware catches it if nobody else did. It gets logged, a response is sent, the request completes. The error doesn't silently disappear into a promise that nobody's waiting for.

Database errors are distinct from business logic errors. A user record wasn't found (business logic—return a 404). The database connection died (infrastructure—return a 503, trigger an alert, maybe retry). These require different responses and different handling.

The Node.js official documentation covers error handling patterns. Read it, then apply them consistently across your codebase. Don't leave error handling as a last-minute thing.

Connection pools and the cascading failures nobody expects

Here's a scenario I've seen happen twice: Your Node.js app handles 10 requests per second in development. You deploy to production. Traffic arrives. Suddenly the app is hanging. The database isn't responding. You restart the app. It works for 20 minutes. It hangs again.

What happened? The connection pool exhausted. Your app tried to open more connections than the database allows. Now every subsequent request is waiting in a queue for a connection to become available. Meanwhile, connections aren't being released because something in your code is holding them open—a long-running query, a missing close(), a transaction that never commits.

Connection pool management is invisible until it breaks. So here's what to do: Set a reasonable pool size—for most applications it's 10-20 connections, not 100. Monitor your pool utilization. If you're regularly at 80%+ capacity, your database is a bottleneck, and you need to either optimize queries or add read replicas. Set a connection timeout—if a connection hasn't been used in 30 minutes, close it. Graceful shutdown: when your app receives SIGTERM, close the pool properly and wait for active connections to finish. Don't just kill the process.

For teams serving clients across Kuwait, Saudi, and the UAE, I'd also recommend: query timeouts. A single slow query can hang your entire pool. Set a 30-second timeout and fail fast. This isn't thrilling stuff. But it's the difference between an app that handles growth and an app that melts at 2 AM.

The three patterns you should copy

I'm going to give you three concrete patterns that work. Not theories—patterns I've shipped in production systems serving customers in Kuwait, Saudi Arabia, and the UAE.

Pattern 1: Structured error responses. Every error response follows the same shape:

{
  "error": true,
  "code": "PAYMENT_FAILED",
  "message": "User-friendly message",
  "requestId": "req_abc123"
}

The requestId links the response to your logs. The code is machine-readable so the frontend knows how to respond. When something breaks, you search your logs by requestId and find the entire context.

Pattern 2: Middleware error catching. All routes use a wrapper that catches rejections:

const asyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next)
}

Every unhandled error goes through a single error middleware. No scattered try-catches. No forgotten error cases. One place to log, one place to format responses.

Pattern 3: Graceful shutdown. When your app receives SIGTERM: stop accepting new requests, wait 10 seconds for in-flight requests to complete, then close the database. A client doesn't get a halfway-closed connection—they get a proper 503 or a timeout.

These three patterns survive everything I've thrown at them.

This matters for your business

A 2 AM production outage costs you customers. Not because the code was buggy—because nobody knew the error happened until it was too late. Get your folder structure intentional. Build error handling from day one, not month six. Manage your connection pools like they matter (they do). Test all of this—test the error paths, test the shutdown sequence, test the connection behavior under load.

If you're building custom Node.js applications for clients in Kuwait, Saudi Arabia, or anywhere in the Gulf, this is the foundation everything else sits on. Need help shipping production-ready Node.js? Reach out on WhatsApp—that's where we work.