Welcome to the technical documentation. This guide provides an overview of the core concepts, architecture, and tools you'll need to get started building with confidence.

Overview#

Modern software systems are built on layers of abstraction — from hardware and operating systems up through runtimes, frameworks, and application logic. Understanding where your code fits in that stack helps you make better architectural decisions, debug faster, and write more maintainable systems.

This documentation assumes familiarity with basic programming concepts such as variables, functions, and control flow. Prior experience with any C-style language (JavaScript, TypeScript, Go, Rust, etc.) will be helpful.

Core Concepts#

Abstraction Layers#

Every technical system is composed of discrete layers, each hiding complexity from the one above it. A web request, for example, travels through:

Application logic — your route handlers and business rules
Runtime / VM — Node.js, the JVM, the browser engine
Operating system — process scheduling, file I/O, networking
Hardware — CPU, memory, network interface cards

Understanding this stack means you can reason about where a problem is occurring rather than guessing blindly.

State and Side Effects#

A core tension in software design is between pure computation (functions that take inputs and return outputs with no observable side effects) and stateful operations (reading from a database, writing a file, sending an HTTP request).

TypeScript

// Pure function — predictable, easy to test
function add(a: number, b: number): number {
  return a + b;
}
 
// Side effect — depends on and mutates external state
async function incrementCounter(id: string): Promise<void> {
  const current = await db.get(id);
  await db.set(id, current + 1);
}

Keeping side effects at the edges of your system and pure logic at the core is a principle shared by functional programming, clean architecture, and hexagonal architecture patterns.

Concurrency vs. Parallelism#

These terms are often used interchangeably, but they mean different things:

Concept Definition Example Concurrency Dealing with multiple tasks at once (interleaving) Node.js event loop handling many HTTP requests Parallelism Executing multiple tasks simultaneously (true multi-core) Rust threads processing image chunks in parallel

Most web servers are concurrent but not necessarily parallel. A single-threaded event loop like Node.js can handle thousands of simultaneous connections by yielding during I/O — no extra threads required.

Getting Started#

Set up your environment

Install the required runtime and package manager for your platform. For most JavaScript/TypeScript projects this means Node.js and a package manager.

Bash

npm install

Understand the project structure

A well-organised project separates concerns into clearly named directories:

Text

src/
  core/        # Pure business logic, no framework dependencies
  adapters/    # I/O: HTTP handlers, database clients, queue consumers
  config/      # Environment variables, feature flags
  utils/       # Shared helpers with no business logic
tests/
  unit/
  integration/

Run your first build

Compile and verify the project builds without errors before making any changes.

Bash

# TypeScript example
npx tsc --noEmit
 
# Run tests
npm test

Key Principles#

Fail Fast#

Detect and surface errors as early as possible — ideally at compile time, then at startup, and only as a last resort at runtime during a user request.

TypeScript

// Bad: silent failure, error surfaces late
function getConfig(key: string): string | undefined {
  return process.env[key];
}
 
// Better: fail at startup if a required value is missing
function requireEnv(key: string): string {
  const value = process.env[key];
  if (!value) throw new Error(`Missing required environment variable: ${key}`);
  return value;
}

Observability Over Debugging#

Instrument your code so that when something goes wrong in production, you have the information you need without having to reproduce the issue locally.

console.log debugging is fine locally, but in production you need structured logs, distributed traces, and metrics. These are not optional for any system that handles real traffic.

The three pillars of observability are:

Logs — discrete, timestamped events (what happened)
Metrics — aggregated numerical measurements over time (how often / how much)
Traces — the causal chain of operations across services (where time was spent)

Untitled