Serving & Structuring an App

Up to now the tasks API has lived in one file - the easiest thing to read while learning the shapes. But every real app outgrows a single file, and the way it grows isn't random. There's a standard Express layout you'll recognize in nearly every Node codebase you open.

The mental model: split by responsibility

You don't split a growing app by file size - you split it by responsibility. Each piece answers one question:

• Routes - which URL maps to which handler? (the wiring)
• Controllers - how do I read the HTTP request and shape the HTTP response? (the web layer)
• Services - what's the actual business logic and data access? (the brains)
• Middleware - what runs in the chain around the handlers? (auth, error handling)

One more split, easy to miss, that pays off hugely: building the app is a different job from starting the server. app.js assembles the middleware and routers and exports the app; server.js imports it and calls app.listen.

💡 This is the Node echo of MVC. Routes point at controllers, controllers stay thin and delegate to services, services hold the logic. Keep handlers thin and the logic lands somewhere you can test without spinning up a web server.

First, a quick win that needs almost no structure: serving files.

Serving static files

A backend rarely serves only JSON - sooner or later you have a built frontend, images, a PDF, a favicon, plain files to hand the browser as-is. Express has one line for that.

const express = require('express');
const app = express();

app.use(express.static('public'));

app.listen(3000);

What just happened: express.static('public') is built-in middleware that serves everything inside a public folder at the root of your site. public/index.html answers at http://localhost:3000/; public/styles.css answers at /styles.css. Images, JS bundles, fonts - all served automatically with the right headers, no routes written. This is how you'd serve a built React/Svelte/Vue frontend out of the same Express app that serves your API.

📝 The path is relative to where you start the process, not where express.static is called from - use path.join(__dirname, 'public') if you ever run the server from a different directory.

For assets that don't change often, add { maxAge: '1d' } - app.use(express.static('public', { maxAge: '1d' })) sets Cache-Control: max-age=86400 so browsers hold the files for a day instead of re-fetching every load. (Files that do change typically rely on hashed filenames so a new build gets a new URL.)

Structure beyond one file

Now the real refactor: spread the tasks API from Phase 5 and Phase 6 across the standard layout. Nothing about the behavior changes - same routes, same status codes, same logic. We're only moving code into the box that matches its job.

tasks-api/
  app.js                       ← builds the app (middleware + routers), exports it
  server.js                    ← imports app, calls app.listen
  routes/
    tasks.routes.js            ← maps URLs → controller functions
  controllers/
    tasks.controller.js        ← reads req, shapes res (thin)
  services/
    tasks.service.js           ← business logic + the data store
  middleware/
    error-handler.js           ← the centralized error handler from Phase 6
  public/                      ← static files (optional)

Let's build it bottom-up - logic first, then the web layer, then the wiring.

The service: logic and data, no HTTP

The service knows nothing about req or res. It deals in plain data and throws plain errors - the whole point is that it's testable without a web server.

// services/tasks.service.js
let tasks = [];
let nextId = 1;

function listTasks() {
  return tasks;
}

function getTask(id) {
  return tasks.find((t) => t.id === id);
}

function createTask(title) {
  const task = { id: nextId++, title, done: false };
  tasks.push(task);
  return task;
}

function deleteTask(id) {
  const index = tasks.findIndex((t) => t.id === id);
  if (index === -1) return false;
  tasks.splice(index, 1);
  return true;
}

module.exports = { listTasks, getTask, createTask, deleteTask };

What just happened: the array and its operations now live behind named functions, with no res.json or status code - the service returns data (getTask returns the task or undefined) and lets the caller decide what HTTP means. This is the seam Phase 5 promised: swap this file for one backed by a real database and the controllers above it don't change.

The controller: read the request, shape the response

The controller is the only layer that touches req and res. It parses input, calls the service, and translates the result into HTTP.

// controllers/tasks.controller.js
const service = require('../services/tasks.service');

function list(req, res) {
  res.json(service.listTasks());
}

function getOne(req, res) {
  const task = service.getTask(Number(req.params.id));
  if (!task) {
    return res.status(404).json({ error: 'Task not found' });
  }
  res.json(task);
}

function create(req, res) {
  const { title } = req.body;
  if (typeof title !== 'string' || title.trim() === '') {
    return res.status(400).json({ error: 'title is required' });
  }
  res.status(201).json(service.createTask(title.trim()));
}

function remove(req, res) {
  const deleted = service.deleteTask(Number(req.params.id));
  if (!deleted) {
    return res.status(404).json({ error: 'Task not found' });
  }
  res.sendStatus(204);
}

module.exports = { list, getOne, create, remove };

What just happened: each function is thin - parse → call service → respond. The Number(req.params.id) coercion and return res.status(...) discipline from Phase 5 still live here, since those are genuinely HTTP concerns; the "find it, mutate the array" mechanics moved to the service. A controller should read like a description of the request/response contract, nothing more.

The routes: pure wiring

The route file does one job: connect a method and path to a controller function. No logic, no validation, no res - just the map.

// routes/tasks.routes.js
const express = require('express');
const controller = require('../controllers/tasks.controller');

const router = express.Router();

router.get('/', controller.list);
router.get('/:id', controller.getOne);
router.post('/', controller.create);
router.delete('/:id', controller.remove);

module.exports = router;

What just happened: this is the Phase 5 router, stripped to the wiring. You can read the entire surface of the resource in five lines - exactly what you want coming back in six months to remember "what URLs does this thing answer?"

app.js vs server.js: build it, then start it

This is the split that trips people up. app.js assembles the application and exports it - it does not call listen. server.js imports that app and starts listening.

// app.js
const express = require('express');
const tasksRoutes = require('./routes/tasks.routes');
const errorHandler = require('./middleware/error-handler');

const app = express();

app.use(express.json());
app.use(express.static('public'));
app.use('/api/tasks', tasksRoutes);

app.use(errorHandler); // error-handling middleware goes LAST

module.exports = app;

// server.js
const app = require('./app');

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Tasks API on http://localhost:${port}`);
});

What just happened: app.js is now a pure recipe for an Express app - middleware, routers, error handler, in the right order (express.json() before routes that need a parsed body; the error handler dead last, per Phase 6). server.js is the one place that actually opens a port.

📝 Why this split is worth the extra file. A test wants to fire requests at your app, not squat a real server on port 3000 (tests run in parallel, ports collide, a left-open server hangs the run). Because app.js exports the app without listening, a test can require('./app') and hand it to a tool like supertest, which drives it in-memory - no port, no listen, no cleanup. That's exactly what Phase 8 does.

Config via the environment

server.js used process.env.PORT - the start of the last piece: configuration belongs in the environment, not in your code.

The same app runs on your laptop, in CI, and in production, and each needs different settings: a different port, database URL, API keys. Hard-coding those means editing source on every deploy and, far worse, committing secrets into git. The fix is process.env - Node hands you every environment variable on that object.

const port = process.env.PORT || 3000;
const databaseUrl = process.env.DATABASE_URL;

What just happened: process.env.PORT reads whatever the environment provides; || 3000 is a fallback for local dev. Your host (Render, Railway, Fly, a Docker ENV) sets PORT and DATABASE_URL in production, and the same code picks them up with zero edits.

Typing PORT=3000 DATABASE_URL=... node server.js every time is miserable. In dev, keep those in a .env file and load it. Two ways:

# Option A - the dotenv package (works on any Node version)
npm install dotenv

// at the very top of server.js, before anything reads process.env
require('dotenv').config();

# Option B - Node's built-in flag (Node 20.6+, no package needed)
node --env-file=.env server.js

What just happened: both read a .env file like the one below and load each line into process.env before your code runs. dotenv is the long-standing package that works everywhere; --env-file is the newer built-in needing no dependency - pick one.

# .env - values for local development only
PORT=3000
DATABASE_URL=postgres://localhost:5432/tasks_dev

⚠️ Never commit .env, and never hard-code secrets. Add .env to .gitignore on day one. A real secret checked into git is checked in forever - it lives in history even after you delete it, and scanners find leaked keys within minutes. Commit a .env.example with the keys but fake values, so a teammate knows what to set without seeing the real thing. In production, you don't use a .env file at all - set real environment variables through your host's dashboard or secrets manager.

Why all this splitting pays off

The controllers are thin - they describe the HTTP contract and nothing else. The logic sits in a service with no web dependencies, so you can test it as plain functions. The routes are a five-line map of the resource. And app.js builds an app that a test can import without ever opening a port.

💡 That's the throughline into the next phase: the layered split keeps handlers thin and logic testable - Node's take on MVC. You restructured so Phase 8 can write real tests against real code without fighting the framework.

Recap

• Split a growing app by responsibility, not by file length: routes (wiring), controllers (HTTP), services (logic + data), middleware (the chain).
• express.static('public') serves a folder of files at the site root - perfect for a built frontend or assets; add { maxAge: '1d' } to let browsers cache them.
• Separate building the app (app.js, exports the app, no listen) from starting it (server.js, calls app.listen) - so tests can import the app without a running server.
• Read config from process.env (PORT, DATABASE_URL); load a .env in dev via dotenv or Node's built-in --env-file.
• Never commit .env or hard-code secrets - gitignore it, ship a .env.example with fake values, and set real env vars in production.

Quick check

[
  {
    "q": "Why does app.js export the app instead of calling app.listen() itself?",
    "choices": ["Because express.json() requires it", "So tests can import the fully-built app and drive it without starting a real server on a port", "Because app.listen only works in production", "To make the file shorter"],
    "answer": 1,
    "explain": "Splitting build (app.js) from start (server.js) lets a test require the app and hand it to a tool like supertest in-memory - no port, no listen, no cleanup. That's what Phase 8 relies on."
  },
  {
    "q": "What does express.static('public') do?",
    "choices": ["Caches all API responses for one day", "Serves the files in the 'public' folder at the site root, with correct content types", "Disables dynamic routes", "Validates incoming JSON bodies"],
    "answer": 1,
    "explain": "It's built-in middleware that serves a folder of files (HTML, CSS, JS, images) at the root - public/index.html answers at /, public/styles.css at /styles.css."
  },
  {
    "q": "Where should the database URL and port come from, and how do you handle secrets?",
    "choices": ["Hard-coded in app.js and committed to git", "From process.env, loaded from a .env in dev that is gitignored; set real env vars in production", "Always passed as command-line arguments by hand", "Stored in the public folder so the frontend can read them"],
    "answer": 1,
    "explain": "Config belongs in the environment (process.env). In dev, load a .env via dotenv or --env-file, but gitignore it and never commit secrets; production sets real environment variables through the host."
  }
]