Node.js Architecture

Good Node architecture is simple, boring, and explicit. Keep boundaries small, isolate I/O, and keep the runtime entrypoint thin.

Common use cases

  • HTTP APIs and backend services.
  • CLI tools and automation scripts.
  • Build tooling, dev servers, and project scaffolding.
  • Real-time apps that need sockets or event-driven I/O.

Layered layout

src/
  app.ts          # process bootstrap and composition root
  routes/         # HTTP or CLI adapters
  services/       # business rules
  data/           # persistence and external I/O
  config/         # environment and startup settings
  types/          # shared domain types

Design rules

  1. Keep the entry file small and startup-only.
  2. Separate business rules from transport code.
  3. Wrap external APIs in adapters so you can replace them later.
  4. Use environment variables for deployment settings, never hard-coded secrets.

Architecture choice

For most Node apps, start with a layered or feature-based architecture. Use a feature-based structure when the app will grow by product area. Use a layered structure when the app is small, service-oriented, or needs a clean separation between HTTP, services, and persistence.

Practice

  1. Sketch a Node app with an entry file, one service, and one adapter.
  2. Mark which file is allowed to touch HTTP and which file contains business rules.
  3. Write one trade-off note about layered versus feature-based structure.