One post tagged with "architecture"

Why Enterprises Chose Node.js + TypeScript​

The original pitch for Node.js was simple: one language on frontend and backend, non-blocking I/O, and npm. That's still true, but enterprises stick with it for different reasons:

• I/O-bound workloads are the majority. API gateways, BFFs, service aggregation layers — most enterprise backend work is waiting on databases, caches, and downstream services, not CPU. Node's event loop is exceptionally efficient here.
• Shared code between teams. Validation schemas, API types, error codes — all can be in a shared package, used by both frontend and backend with zero serialization ceremony.
• TypeScript changed the ROI calculation. The original knock on Node.js at scale was "JavaScript doesn't scale with team size." TypeScript neutralized that argument. Strict types, IDE autocomplete, and refactoring confidence are what made Node viable for 100-engineer codebases.

The combination is now the dominant stack for: API gateways, backend-for-frontends (BFFs), developer tooling, real-time services, and internal microservices.

Architecture: How Enterprises Structure Node.js at Scale​

The Monorepo​

Large engineering orgs almost universally use a monorepo for their Node.js/TypeScript services. The tooling has matured significantly — Nx, Turborepo, and pnpm workspaces are the main players.

Why monorepos at scale:

• Atomic commits across services — if you change a shared type, you fix every consumer in the same PR.
• Unified CI/CD pipeline with affected-build detection — only rebuild what changed.
• Shared tsconfig, eslint, and prettier configs enforced across the whole org.
• Internal packages (libraries) without the overhead of npm publishing.

/apps
  /api-gateway        ← Express/Fastify entry point
  /user-service
  /order-service
  /notification-service
/packages
  /dto                ← shared request/response types
  /errors             ← shared error classes and codes
  /logger             ← structured logging wrapper
  /db                 ← TypeORM data source and entities
  /config             ← environment config with validation

TypeScript project references (references in tsconfig.json) allow incremental builds across packages — only changed packages recompile.

Microservices vs Modular Monolith​

Not every enterprise jumps straight to microservices. The pattern that's worked well in practice:

1. Start with a modular monolith. Separate your domains into modules (User, Order, Payment) with clear boundaries — no cross-module DB queries, communication only through defined interfaces.
2. Extract services when you have a real reason: independent scaling needs, different deployment cadence, or team ownership boundaries.
3. Never extract before the boundary is stable. Premature microservice extraction is the biggest source of distributed systems complexity with none of the benefits.

Netflix famously uses thousands of microservices, but they also have thousands of engineers. At 50 engineers, a well-modularized monolith is almost always the right answer.

TypeScript at Scale: The Practices That Actually Matter​

Strict Mode — Non-Negotiable​

Every enterprise TypeScript codebase that's aged well has strict: true from day one.

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

noUncheckedIndexedAccess is the most underused option — it makes arr[0] return T | undefined, forcing you to handle the case where the index doesn't exist. This single flag catches an entire class of runtime bugs at compile time.

Code Generation from the Source of Truth​

At scale, the biggest type-safety risk is the gap between what your API says it returns and what it actually returns. Enterprises solve this by generating types from authoritative sources:

The pattern: define once, generate everywhere. No hand-written API types that drift from the actual implementation.

Branded / Nominal Types​

TypeScript's type system is structural — UserId (a number) and OrderId (also a number) are interchangeable by default. At scale, passing the wrong ID to the wrong function is a real bug. Enterprises use branded types to make the compiler catch it:

type Brand<T, B> = T & { readonly _brand: B };

type UserId  = Brand<number, 'UserId'>;
type OrderId = Brand<number, 'OrderId'>;

function getOrder(orderId: OrderId) { ... }

const userId = 1 as UserId;
getOrder(userId);  // ✅ TypeScript error — UserId is not assignable to OrderId

Runtime Validation at System Boundaries​

TypeScript types are erased at runtime. An HTTP request body typed as CreateUserDto is just unknown until validated. Enterprises validate at every system boundary — incoming HTTP, message queue consumers, config values.

The dominant libraries: Zod (schema-first, infer TypeScript types from the schema) and class-validator (decorator-based, pairs well with NestJS).

import { z } from 'zod';

const CreateUserSchema = z.object({
  name:  z.string().min(1).max(100),
  email: z.string().email(),
  role:  z.enum(['admin', 'member']),
});

type CreateUserDto = z.infer<typeof CreateUserSchema>;  // type derived from schema

// In controller
const body = CreateUserSchema.parse(req.body);  // throws ZodError with field-level detail if invalid

One schema = one type. They never drift.

Scalability Patterns​

Clustering​

Node.js is single-threaded. A single process can only use one CPU core. In production, enterprises use the cluster module (or PM2) to spawn one worker per CPU core, putting all cores to work.

import cluster from 'cluster';
import os from 'os';

if (cluster.isPrimary) {
  const cpus = os.cpus().length;
  for (let i = 0; i < cpus; i++) cluster.fork();
  cluster.on('exit', () => cluster.fork());   // respawn crashed workers
} else {
  // each worker runs the full Express/Fastify app
  startServer();
}

In Kubernetes environments, enterprises instead run one process per container and scale horizontally at the pod level — simpler and easier to observe than intra-process clustering.

Worker Threads for CPU-Bound Work​

The event loop stalls when you do CPU-heavy work (JSON parsing large payloads, image processing, cryptographic operations, report generation). Worker threads run JS in a separate V8 context with a shared memory channel, keeping the event loop free.

import { Worker, isMainThread, parentPort, workerData } from 'worker_threads';

// worker.ts
if (!isMainThread) {
  const result = heavyCpuWork(workerData);
  parentPort!.postMessage(result);
}

// main thread
function runInWorker<T>(data: unknown): Promise<T> {
  return new Promise((resolve, reject) => {
    const worker = new Worker('./worker.ts', { workerData: data });
    worker.on('message', resolve);
    worker.on('error', reject);
  });
}

Enterprises typically maintain a worker thread pool (via the piscina library) to avoid the overhead of spawning a new thread per task.

Message Queues​

For work that doesn't need to be in-process or synchronous, message queues decouple services and absorb traffic spikes. The common patterns:

• BullMQ (Redis-backed) — for job queues within a Node.js ecosystem. Retries, delays, priorities, rate limiting, and UI dashboards built in.
• Kafka — for high-throughput event streaming between services. LinkedIn's original use case. Used when you need replay, partitioned ordering, or fan-out to many consumers.
• RabbitMQ / SQS — for point-to-point async messaging between services.

A typical enterprise pattern: the API handler validates and enqueues the job, returns 202 Accepted immediately, and a background worker processes it. The caller polls or gets notified via webhook when done.

Caching Strategy​

Client → CDN (static, edge) → API Gateway → Redis (hot data) → Database

Enterprises cache at multiple layers:

• In-process cache (LRU via lru-cache) — for frequently read, rarely changing config or reference data. Zero network latency, but not shared across instances.
• Redis — the standard shared cache. Used for session data, rate limiting counters, computed aggregations, and full response caching.
• Cache-aside pattern — service checks Redis first; on miss, hits DB and writes to Redis. TTL chosen per data type.

The hard problems at scale: cache invalidation (when does stale data become a bug?), thundering herd (100 instances all miss cache at the same time), and hot keys (one cache key getting millions of reads per second).

Observability​

At scale, console.log is not a logging strategy. The three pillars of observability enterprises implement:

Structured Logging​

Every log line is a JSON object, not a freeform string. This makes logs queryable in tools like Datadog, Grafana Loki, or Splunk.

// Using pino — the fastest JSON logger for Node.js
import pino from 'pino';

const logger = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  base: { service: 'order-service', version: process.env.APP_VERSION },
});

// Every log includes structured context
logger.info({ orderId, userId, total }, 'Order created');
logger.error({ err, orderId }, 'Payment failed');

Key fields that every enterprise log includes: traceId, spanId, userId, service, version, environment. This lets you filter logs for a single request across 50 service instances.

Distributed Tracing​

When a single user request touches 10 services, you need to see the full call tree, where time was spent, and where it failed. OpenTelemetry is the standard — it instruments HTTP clients, DB drivers, and message queue clients automatically.

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_ENDPOINT }),
  // auto-instruments express, pg, redis, http, etc.
});
sdk.start();

Every trace gets a traceId. Pass it in HTTP headers (traceparent) to stitch spans across services into one waterfall view.

Metrics​

Enterprises expose a /metrics endpoint (Prometheus format) and scrape it. Key metrics for a Node.js service:

Event loop lag is the most Node.js-specific metric. A lag above 100ms means your event loop is blocked by CPU work and request handling is degrading.

Error Handling​

Unhandled promise rejections and uncaught exceptions crash Node.js processes. Enterprises standardize error handling at every layer.

Typed Error Hierarchy​

export class AppError extends Error {
  constructor(
    public readonly code: string,
    message: string,
    public readonly statusCode: number = 500,
    public readonly context?: Record<string, unknown>,
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id: unknown) {
    super('NOT_FOUND', `${resource} not found`, 404, { resource, id });
  }
}

export class ValidationError extends AppError {
  constructor(details: unknown) {
    super('VALIDATION_ERROR', 'Validation failed', 422, { details });
  }
}

Global Error Middleware​

// Express global error handler
app.use((err: unknown, req: Request, res: Response, _next: NextFunction) => {
  if (err instanceof AppError) {
    logger.warn({ err, traceId: req.traceId }, err.message);
    return res.status(err.statusCode).json({
      code: err.code,
      message: err.message,
    });
  }
  // Unknown error — log full stack, return generic 500
  logger.error({ err, traceId: req.traceId }, 'Unhandled error');
  res.status(500).json({ code: 'INTERNAL_ERROR', message: 'Something went wrong' });
});

// Catch unhandled rejections — log and gracefully shut down
process.on('unhandledRejection', (reason) => {
  logger.fatal({ reason }, 'Unhandled promise rejection');
  process.exit(1);
});

Configuration Management​

Hardcoded config is a security and ops nightmare. Enterprises validate all config at startup — if a required env var is missing, the service crashes immediately with a clear error rather than failing silently at runtime.

import { z } from 'zod';

const ConfigSchema = z.object({
  PORT:         z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL:    z.string().url(),
  JWT_SECRET:   z.string().min(32),
  LOG_LEVEL:    z.enum(['debug', 'info', 'warn', 'error']).default('info'),
  NODE_ENV:     z.enum(['development', 'test', 'production']),
});

export const config = ConfigSchema.parse(process.env);
// If DATABASE_URL is missing → throws at startup with "Required" error
// config.PORT is typed as number, not string

Secrets (DB passwords, API keys, JWT secrets) come from a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager) — never from .env files in production.

Testing Strategy​

Enterprises run three layers of tests, and they are deliberate about which layer covers what:

Unit Tests​

Pure functions, business logic, transformations. No DB, no HTTP. Fast — run in milliseconds. Cover edge cases exhaustively here.

Integration Tests​

A service with its real database and real Redis, but no external services (those are replaced with test doubles or a contract test). This is where TypeORM queries, migrations, and cache behavior get tested.

// Integration test with a real DB
beforeAll(async () => {
  await AppDataSource.initialize();
  await AppDataSource.runMigrations();
});

afterEach(async () => {
  await AppDataSource.query('TRUNCATE TABLE orders CASCADE');
});

Contract Tests (Pact)​

In a microservices org, integration tests can't realistically spin up every upstream/downstream service. Contract tests define the API contract between a consumer and provider — each side verifies their half independently. This is what allows teams to deploy independently without breaking each other.

Load Tests​

k6 or Artillery for sustained load tests before major releases. Enterprise teams measure p99 latency and error rate under expected peak traffic — not just average behavior.

Deployment and Graceful Shutdown​

Kubernetes is the dominant deployment platform for Node.js at scale. A few patterns that matter:

Graceful Shutdown​

When Kubernetes kills a pod (rolling deploy, scale-down), it sends SIGTERM. A well-behaved service:

1. Stops accepting new requests.
2. Waits for in-flight requests to complete.
3. Closes DB connections and message queue consumers.
4. Exits with code 0.

const server = app.listen(config.PORT);

async function shutdown() {
  logger.info('Shutting down...');
  server.close(async () => {
    await AppDataSource.destroy();
    await redisClient.quit();
    logger.info('Shutdown complete');
    process.exit(0);
  });
}

process.on('SIGTERM', shutdown);
process.on('SIGINT',  shutdown);

Without graceful shutdown, rolling deploys drop in-flight requests. Kubernetes waits 30 seconds (configurable via terminationGracePeriodSeconds) before force-killing.

Health Checks​

// Liveness — is the process alive and not deadlocked?
app.get('/health/live', (_, res) => res.json({ status: 'ok' }));

// Readiness — is the service ready to serve traffic?
app.get('/health/ready', async (_, res) => {
  try {
    await AppDataSource.query('SELECT 1');
    await redisClient.ping();
    res.json({ status: 'ok' });
  } catch (err) {
    res.status(503).json({ status: 'unavailable' });
  }
});

Kubernetes uses the readiness probe to decide whether to route traffic to a pod. During startup (while migrations run, connections establish), the readiness probe returns 503 — the pod gets no traffic until it's actually ready.

Real-World Examples​

PayPal's 2013 migration from Java to Node.js is one of the most cited case studies: they rebuilt their account overview page and found the Node.js version was built with twice the productivity, 33% fewer lines of code, and delivered twice the requests per second compared to Java. That finding echoed across the industry.

What to Avoid at Scale​

• any type — it's a type-safety escape hatch that spreads. One any infects everything it touches. Use unknown + type guards instead.
• Synchronous file I/O in the request path — fs.readFileSync, JSON.parse on multi-MB payloads, crypto.pbkdf2Sync. All block the event loop.
• Unbounded concurrency — Promise.all(items.map(item => fetchFromDB(item))) with 10,000 items opens 10,000 DB connections simultaneously. Use p-limit or piscina to bound concurrency.
• Memory leaks in long-running processes — event listeners not removed, caches with no eviction, closures holding references. Use --expose-gc and heap snapshots in staging to catch these before production.
• Fat lambdas — running a full Express app inside a Lambda/Cloud Function. Cold start times multiply with every dependency. Lambdas work well for Node.js; just keep them focused and dependencies minimal.

The Stack That Works​

There's no single "enterprise Node.js stack" — but there is a clear convergence in what mature orgs use:

Node.js and TypeScript at scale is less about any single technology and more about discipline: strict types enforced by CI, validated boundaries, observable systems, and a clear deployment contract. The companies that run it well treat the runtime as a foundation and invest heavily in the tooling around it.

The event loop is fast. The question is whether your architecture, types, and observability keep up with it.