Software architecture

// The same small app, built two ways. Which files would you
// have to edit to switch to a different database?
const scattered = {
  "pages/catalog.js":  ["sql", "html"],
  "pages/cart.js":     ["sql", "html"],
  "pages/checkout.js": ["sql", "html", "payments"],
  "jobs/emails.js":    ["sql", "email"],
  "jobs/reports.js":   ["sql", "csv"],
  "admin/books.js":    ["sql", "html"],
};
const behindABoundary = {
  "pages/catalog.js":  ["books", "html"],
  "pages/cart.js":     ["books", "html"],
  "pages/checkout.js": ["orders", "html", "payments"],
  "jobs/emails.js":    ["orders", "email"],
  "jobs/reports.js":   ["orders", "csv"],
  "admin/books.js":    ["books", "html"],
  "storage/books.js":  ["sql"],     // the only two files that know
  "storage/orders.js": ["sql"],     // there is a database at all
};
​
function blastRadius(app, decision) {
  return Object.keys(app).filter((file) => app[file].includes(decision));
}
​
console.log("scattered:", blastRadius(scattered, "sql"));
console.log("behind a boundary:", blastRadius(behindABoundary, "sql"));

// A module: a small public surface, and secrets behind it.
function createCart(prices) {
  const lines = new Map();          // private: nothing outside can reach it
​
  function add(isbn, qty = 1) {
    if (!(isbn in prices)) throw new Error("unknown book " + isbn);
    lines.set(isbn, (lines.get(isbn) ?? 0) + qty);
  }
  function total() {
    let sum = 0;
    for (const [isbn, qty] of lines) sum += prices[isbn] * qty;
    return sum;
  }
  return { add, total };            // the interface: two functions
}
​
const cart = createCart({ "978-0": 30, "978-1": 12 });
cart.add("978-0");
cart.add("978-1", 2);
console.log("total:", cart.total());
console.log("can I see the lines?", cart.lines);

// Who depends on whom in the bookshop (arrows point at what you use)
const deps = {
  catalog:  [],
  cart:     ["catalog"],
  orders:   ["cart", "payments", "shipping", "accounts"],
  payments: [],
  shipping: ["accounts"],
  accounts: [],
};
​
for (const m of Object.keys(deps)) {
  const fanOut = deps[m].length;                                       // I use them
  const fanIn = Object.values(deps).filter((d) => d.includes(m)).length; // they use me
  const instability = fanOut / (fanIn + fanOut || 1);
  console.log(m.padEnd(9), "in", fanIn, " out", fanOut, " instability", instability.toFixed(2));
}

// DATA layer: knows how to store things, nothing about rules or screens
const bookTable = new Map([["978-0", { title: "Dune", stock: 3, price: 30 }]]);
const data = {
  find: (isbn) => bookTable.get(isbn),
  save: (isbn, book) => bookTable.set(isbn, book),
};
​
// DOMAIN layer: the rules of the business, nothing about HTML or SQL
const domain = {
  buy(isbn, qty) {
    const book = data.find(isbn);
    if (!book) return { ok: false, reason: "no such book" };
    if (book.stock < qty) return { ok: false, reason: "only " + book.stock + " left" };
    data.save(isbn, { ...book, stock: book.stock - qty });
    return { ok: true, cost: book.price * qty };
  },
};
​
// PRESENTATION layer: turns requests into calls, and results into words
function handle(request) {
  const r = domain.buy(request.isbn, request.qty);
  return r.ok ? "200 Thanks! That's $" + r.cost : "409 Sorry: " + r.reason;
}
​
console.log(handle({ isbn: "978-0", qty: 2 }));
console.log(handle({ isbn: "978-0", qty: 2 }));
console.log(handle({ isbn: "999-9", qty: 1 }));

// THE CORE: one use case. It talks only to ports: objects it is handed.
function makePlaceOrder({ orders, payments, clock }) {
  return function placeOrder(customer, items) {
    const total = items.reduce((sum, it) => sum + it.price * it.qty, 0);
    if (total <= 0) throw new Error("empty order");
    if (!payments.charge(customer, total)) return { status: "declined" };
    const order = { id: orders.nextId(), customer, total, at: clock.now() };
    orders.save(order);
    return { status: "placed", id: order.id };
  };
}
​
// DRIVEN ADAPTERS: two ways to store orders, one fake way to pay
function inMemoryOrders() {
  const rows = [];
  return { nextId: () => rows.length + 1, save: (o) => rows.push(o), count: () => rows.length };
}
function sqlOrders(sent) {          // pretends to talk to a SQL database
  let id = 100;
  return {
    nextId: () => ++id,
    save: (o) => sent.push(["INSERT INTO orders VALUES ($1, $2, $3)", o.id, o.customer, o.total]),
  };
}
const testPayments = { charge: (who, amount) => amount < 500 };
const fixedClock = { now: () => "2026-10-11T09:00" };
​
// DRIVING ADAPTER 1: the production wiring (a web handler would call this)
const sent = [];
const live = makePlaceOrder({ orders: sqlOrders(sent), payments: testPayments, clock: fixedClock });
console.log(live("ada", [{ price: 30, qty: 2 }]));
console.log(sent[0]);
​
// DRIVING ADAPTER 2: a test. Same core, no database at all.
const mem = inMemoryOrders();
const test = makePlaceOrder({ orders: mem, payments: testPayments, clock: fixedClock });
console.log(test("bob", [{ price: 600, qty: 1 }]));
console.log(test("bob", [{ price: 12, qty: 1 }]), "stored:", mem.count());

// BEFORE: the policy builds its own detail. The arrow points down.
class MySqlDatabase {
  insert(row) { throw new Error("can't reach a database server from here"); }
}
class SignupServiceBefore {
  constructor() { this.db = new MySqlDatabase(); }  // hard-wired detail
  signup(email) {
    if (!email.includes("@")) return false;
    this.db.insert({ email });
    return true;
  }
}
​
// AFTER: the policy says what it needs ("something with save(user)"),
// and whoever starts the program hands it in.
class SignupService {
  constructor(users) { this.users = users; }       // depends on an idea, not a product
  signup(email) {
    if (!email.includes("@")) return false;
    this.users.save({ email });
    return true;
  }
}
​
const saved = [];
const fakeUsers = { save: (user) => saved.push(user) };   // a test double
const service = new SignupService(fakeUsers);
console.log(service.signup("ada@example.com"), service.signup("nope"));
console.log("saved:", saved);
​
try { new SignupServiceBefore().signup("ada@example.com"); }
catch (e) { console.log("before:", e.message); }

// One program, many modules. Each declares what it needs, and only
// gets the public API of exactly those modules.
const registry = new Map();
function defineModule(name, needs, build) { registry.set(name, { needs, build }); }
​
function start(name, app, path = []) {
  if (app.has(name)) return app.get(name);
  if (path.includes(name)) throw new Error("cycle: " + [...path, name].join(" → "));
  const { needs, build } = registry.get(name);
  const allowed = {};
  for (const dep of needs) allowed[dep] = start(dep, app, [...path, name]);
  const api = Object.freeze(build(allowed));      // nobody can patch it later
  app.set(name, api);
  return api;
}
​
defineModule("catalog", [], () => {
  const prices = { dune: 30, emma: 12 };          // private to catalog
  return { priceOf: (book) => prices[book] };
});
defineModule("cart", ["catalog"], ({ catalog }) => {
  const items = [];
  return {
    add: (book) => { items.push(book); },
    total: () => items.reduce((sum, b) => sum + catalog.priceOf(b), 0),
  };
});
defineModule("orders", ["cart"], ({ cart, catalog }) => ({
  checkout() {
    console.log("can orders see catalog?", catalog);   // not declared, so no
    return { total: cart.total() };
  },
}));
​
const app = new Map();
for (const name of registry.keys()) start(name, app);
app.get("cart").add("dune");
app.get("cart").add("emma");
console.log(app.get("orders").checkout());

// One checkout touches 5 other parts. Rough costs, from the well-known
// "latency numbers every programmer should know":
const CALL_MS = 0.0001;    // a function call in the same process: ~100 ns, generous
const HOP_MS = 0.5;        // one network round trip inside a datacenter
const UP = 0.999;          // each running service is up 99.9% of the time
​
const parts = ["cart", "catalog", "payments", "shipping", "accounts"];
​
const monolith = { ms: parts.length * CALL_MS, up: UP };            // one thing to keep up
const services = { ms: parts.length * HOP_MS, up: UP ** (parts.length + 1) }; // orders + 5
​
const hoursDown = (up) => ((1 - up) * 365 * 24).toFixed(1);
console.log("monolith:      ", monolith.ms.toFixed(4), "ms of calls,", hoursDown(monolith.up), "h down a year");
console.log("microservices: ", services.ms.toFixed(4), "ms of calls,", hoursDown(services.up), "h down a year");
console.log("slower by", Math.round(services.ms / monolith.ms) + "x");

// A function call can't time out. A network call can.
let seed = 7;                                  // a seeded random: same run every time
const rand = () => (seed = (seed * 16807) % 2147483647) / 2147483647;
​
function callShipping() {                      // pretend remote service
  const r = rand();
  if (r < 0.25) throw new Error("timeout after 500 ms");
  if (r < 0.35) throw new Error("503 service unavailable");
  return { days: 2 };
}
​
function withRetry(fn, tries) {
  for (let i = 1; i <= tries; i++) {
    try { return fn(); }
    catch (e) { console.log("   try " + i + " failed: " + e.message); }
  }
  return null;                                 // give up: the caller must cope
}
​
for (let order = 1; order <= 6; order++) {
  const quote = withRetry(callShipping, 2);
  console.log("order " + order + ": " + (quote ? "delivery in " + quote.days + " days" : "delivery date to follow"));
}

function createBus() {
  const handlers = {};
  return {
    subscribe(type, fn) { (handlers[type] ??= []).push(fn); },
    publish(type, data) {
      console.log("event:", type, JSON.stringify(data));
      for (const fn of handlers[type] ?? []) fn(data);
    },
  };
}
const bus = createBus();
​
// Each listener lives in its own module. Orders knows none of them.
bus.subscribe("OrderPlaced", (o) => console.log("  shipping: pack order", o.id));
bus.subscribe("OrderPlaced", (o) => console.log("  email: receipt to", o.customer));
bus.subscribe("OrderPlaced", (o) => console.log("  stats: revenue +", o.total));
​
function placeOrder(id, customer, total) {
  // ...check and save the order, then announce the fact:
  bus.publish("OrderPlaced", { id, customer, total });
}
​
placeOrder(1, "ada", 42);
// A new feature is a new subscriber. placeOrder doesn't change.
bus.subscribe("OrderPlaced", (o) => console.log("  loyalty:", Math.floor(o.total / 10), "points"));
placeOrder(2, "bob", 99);

// WRITE side: commands are checked, then recorded as events (facts).
const events = [];
function handle(cmd) {
  if (cmd.type === "PlaceOrder") {
    if (cmd.total <= 0) throw new Error("rejected: empty order");
    events.push({ type: "OrderPlaced", id: cmd.id, customer: cmd.customer, total: cmd.total });
  }
  if (cmd.type === "CancelOrder") {
    const placed = events.find((e) => e.type === "OrderPlaced" && e.id === cmd.id);
    if (!placed) throw new Error("rejected: no order " + cmd.id);
    events.push({ type: "OrderCancelled", id: cmd.id });
  }
}
​
// READ side: a projection folds the events into exactly the shape a screen needs.
function spendPerCustomer(events) {
  const orders = {}, view = {};
  for (const e of events) {
    if (e.type === "OrderPlaced") {
      orders[e.id] = e;
      view[e.customer] = (view[e.customer] ?? 0) + e.total;
    }
    if (e.type === "OrderCancelled") view[orders[e.id].customer] -= orders[e.id].total;
  }
  return view;
}
​
handle({ type: "PlaceOrder", id: 1, customer: "ada", total: 30 });
handle({ type: "PlaceOrder", id: 2, customer: "bob", total: 12 });
handle({ type: "PlaceOrder", id: 3, customer: "ada", total: 18 });
handle({ type: "CancelOrder", id: 1 });
​
console.log(events.length, "events recorded");
console.table(spendPerCustomer(events));

// Repository: domain code asks for objects as if from a collection.
// How they are stored is the repository's business, and nobody else's.
class InMemoryBookRepository {
  #rows = new Map();
  add(book) { this.#rows.set(book.isbn, { ...book }); }
  byIsbn(isbn) { const r = this.#rows.get(isbn); return r ? { ...r } : null; }
  cheaperThan(price) { return [...this.#rows.values()].filter((b) => b.price < price); }
}
​
// Domain code: no SQL, no Map. Just "the books".
function saleLabels(books, limit) {
  return books.cheaperThan(limit).map((b) => b.title + " now $" + (b.price * 0.9).toFixed(2));
}
​
const books = new InMemoryBookRepository();
books.add({ isbn: "1", title: "Dune", price: 30 });
books.add({ isbn: "2", title: "Emma", price: 8 });
books.add({ isbn: "3", title: "Ulysses", price: 9 });
saleLabels(books, 10);

// Adapter: make something with the wrong shape fit the shape you need.
// Our core wants:  notifier.send(person, text)
// An old SMS library offers this instead:
const oldSms = {
  transmit(payload) { console.log("SMS to", payload.number + ":", payload.body); return { code: 0 }; },
};
​
function smsNotifier(sms) {                  // the adapter
  return {
    send(person, text) {
      const res = sms.transmit({ number: person.phone, body: text.slice(0, 160) });
      if (res.code !== 0) throw new Error("SMS failed with code " + res.code);
    },
  };
}
const emailNotifier = { send: (person, text) => console.log("email to", person.email + ":", text) };
​
function remindAll(people, notifier) {       // the core knows only send()
  for (const p of people) notifier.send(p, "Your books ship today");
}
const people = [{ email: "ada@example.com", phone: "555-0101" }];
remindAll(people, emailNotifier);
remindAll(people, smsNotifier(oldSms));

// Observer: a subject keeps a list of observers and tells them when it changes.
class Stock {
  #observers = new Set();
  #count;
  constructor(count) { this.#count = count; }
  subscribe(fn) {
    this.#observers.add(fn);
    return () => this.#observers.delete(fn);   // call this to unsubscribe
  }
  take(n) {
    this.#count -= n;
    for (const fn of this.#observers) fn(this.#count);
  }
}
​
const dune = new Stock(5);
dune.subscribe((left) => console.log("shop page: " + left + " left"));
const stop = dune.subscribe((left) => { if (left < 3) console.log("buyer: reorder Dune!"); });
dune.take(1);
dune.take(2);
stop();
dune.take(1);

// Strategy: one job, several interchangeable ways to do it.
// In JavaScript a strategy is usually just a function.
const shipping = {
  standard: (kg) => 4 + kg * 1,
  express:  (kg) => 12 + kg * 2.5,
  pickup:   () => 0,
};
​
function quote(cartKg, method) {
  const cost = shipping[method](cartKg);       // which algorithm? chosen at run time
  return method.padEnd(8) + " $" + cost.toFixed(2);
}
​
for (const method of Object.keys(shipping)) console.log(quote(2, method));

// An architecture test: an ADR said "domain code never imports
// infrastructure". Run this in CI and the decision checks itself.
const imports = [
  ["domain/order.js",   "domain/money.js"],
  ["domain/order.js",   "infra/postgres.js"],   // breaks the rule
  ["web/routes.js",     "domain/order.js"],
  ["infra/postgres.js", "domain/order.js"],
  ["web/main.js",       "infra/postgres.js"],   // the entry point wires things up
];
const allowed = {
  web:    ["web", "domain", "infra"],
  domain: ["domain"],
  infra:  ["infra", "domain"],
};
const area = (file) => file.split("/")[0];
​
const broken = imports.filter(([from, to]) => !allowed[area(from)].includes(area(to)));
for (const [from, to] of broken) console.log("✗", from, "must not import", to);
console.log(broken.length === 0 ? "architecture OK" : broken.length + " violation(s)");

const modules = ["catalog", "cart", "orders", "payments", "shipping", "accounts"];
const deps = [["cart", "catalog"], ["orders", "cart"], ["orders", "payments"],
              ["orders", "shipping"], ["orders", "accounts"], ["shipping", "accounts"]];
​
// A dependency between two teams' code means the two teams must talk.
const meetings = (owner) => deps.filter(([a, b]) => owner[a] !== owner[b]).length;
​
const today = { catalog: "A", cart: "B", orders: "C", payments: "A", shipping: "B", accounts: "C" };
console.log("today:", meetings(today), "cross-team dependencies");
​
// Try every way to give three teams two modules each.
let best = null;
function assign(i, owner, load) {
  if (i === modules.length) {
    const m = meetings(owner);
    if (!best || m < best.m) best = { m, owner: { ...owner } };
    return;
  }
  for (const team of ["A", "B", "C"]) {
    if (load[team] === 2) continue;
    owner[modules[i]] = team; load[team]++;
    assign(i + 1, owner, load);
    load[team]--;
  }
}
assign(0, {}, { A: 0, B: 0, C: 0 });
console.log("best:", best.m, "cross-team dependencies");
console.log(best.owner);

// The old system keeps running. A router in front sends each route either
// to the legacy code or to its replacement, one route at a time.
const legacy = (req) => "legacy " + req.path;
const replacements = {
  "/catalog": () => "new catalog",
  "/cart": () => "new cart",
};
const migrated = new Set(["/catalog"]);        // grows week by week
const trial = { "/cart": 50 };                 // new cart for 50% of users
​
function bucket(user) {                        // same user, same bucket, every time
  let h = 0;
  for (const ch of user) h = (h * 31 + ch.charCodeAt(0)) % 100;
  return h;
}
​
function route(req) {
  if (migrated.has(req.path)) return replacements[req.path](req);
  if (bucket(req.user) < (trial[req.path] ?? 0)) return replacements[req.path](req);
  return legacy(req);
}
​
for (const user of ["ada", "bob", "cy", "dee"]) {
  const paths = ["/catalog", "/cart", "/orders"];
  console.log(user.padEnd(4), paths.map((path) => route({ path, user })).join(" | "));
}