seriesoftubes/docs/ARCHITECTURE.md
Frederic Jung c76dd4d556
Benchmark in real Chromium too, and only call a row slower when the samples say so
npm run perf -- --browser times the same workloads in Chromium as a desktop
and as a phone (390x844 at 3x, CPU slowed 4x), one browser per version. Each
run collects garbage first and ends by forcing layout and the map canvas, so
deferred work counts. The jsdom DOM is about 30x slower than a browser's and
has no layout, so the interface rows need this.

Shared machines swing single runs by 30% on identical code, CPU time
included. A row now counts as slower or faster only when it moved 15% and a
Mann-Whitney U test gives p < 0.01 (15 runs a side by default). Identical
code: no flags in three full runs; a routing slowdown planted in a copy is
flagged in jsdom and on the phone.

The panel workload renders both selections every run instead of alternating,
which split its samples in two. CI drives the runner's Chrome through
playwright-core, no browser download.
2026-10-26 12:04:57 +01:00

8.4 KiB
Raw Blame History

Architecture

Everything that runs in the browser lives in site/index.html. It is large (several thousand lines), so find things by the section banners rather than by line number:

/* ================= PHONES ================= */      phone CSS
/* ================= LANGUAGE ================= */    tr(), trn(), N_(), dictionary loading
/* ================= ANALYTICS ================= */   privacy-friendly event counter
/* ================= CONSTANTS ================= */   prices, ports (PORT), routers (RG), optics
/* ================= WORLD ================= */       CITIES, CABLES, display nudges
/* ================= NETWORKS ================= */    NETS (other ASes), traffic shares (NSH)
/* ================= BUSINESSES ================= */  BIZ_T customer types, LEVELS + LV_REQ (13 levels, traffic eras)
/* ================= GOALS ================= */       GOALS checklist
/* ================= STATE ================= */       S, R, UI globals
/* ================= BANKS & LOANS ================= */
   scenarios (SCN), conferences, tutorial, traceroute, share card
/* ================= HELPERS ================= */     formatting, geometry, small queries
/* ================= SIMULATION ================= */  RouteScript, compute(), costs, sanitize()
   failures & events, daily tick, badges
/* ================= ACTIONS ================= */     the ACT map: every player action
/* ================= SAVE ================= */
/* ================= AUDIO ================= */
/* ================= DOM RENDER ================= */  HUD, left panel, side panel, modals, toasts
/* ================= PHONE ================= */       tab bar, bottom sheets
/* ================= INSTALL (PWA) ================= */
/* ================= CANVAS ================= */      map drawing, level of detail
/* ================= LOOP ================= */        frame(), boot()

Other files:

Path What it is
site/i18n/it.js Italian dictionary: English text → Italian, loaded when the language is it
site/i18n/pt.js Portuguese (Brazil) dictionary: English text → Portuguese, loaded when the language is pt
site/sw.js Service worker: network-first for pages, stale-while-revalidate for assets. Cache name is stamped with the version
site/site.webmanifest, icons PWA install metadata
scripts/build.sh Copies site/ to _site/, stamps __VERSION__/__BUILD_DATE__, bakes release notes, writes version.json
scripts/release-notes.js Extracts a version's CHANGELOG bullets
scripts/perf-bench.js, scripts/perf-browser.js, scripts/perf-stats.js, scripts/perf-fixture.js Big-network benchmark, base vs head, headless and in Chromium as a desktop and a throttled phone, with a significance test per row (posted on every PR by perf.yml + perf-comment.yml), and the generator of its save, tests/fixtures/big-network.json
scripts/i18n-check.js Compares every tr/trn/N_ literal and data-i18n text with each dictionary
tests/harness.js Loads the page in jsdom with a seeded Math.random and a fake canvas
.github/workflows/ci.yml Tests and build on every push and PR
.github/workflows/auto-release.yml On a package.json version bump on main: test, tag, GitHub release from the CHANGELOG, start the deploy
.github/workflows/release.yml Builds and deploys to GitHub Pages

Globals

  • S: the whole saved game (one JSON object). Cash, day, POPs, links, transit, IX ports, PNIs, caches, customers (biz), offers, incidents (inc), live events (ev), stats, settings. Saved to localStorage key sot-save-v1.
  • R: results of the last compute(): per-link load, per-exit use, served and demanded traffic, reach, costs and revenue. Never saved; always rebuilt.
  • UI: view state (selection, open tabs, speed, confirmations). Not game state.
  • cam: map camera (x, y, zoom).

Lookup tables built at load: CITY[id], NET[id], CABLE, FAB, BIZ_T, REQS.

The life of a day

frame() (requestAnimationFrame) accumulates time; every DAY_MS × speed it calls dayTick(), at most four times per frame, each inside a try/catch so one bad tick never freezes the game.

dayTick():

  1. Advances S.day, runs scheduled world events (conferences, IX price wars, licences).
  2. Runs compute() to route today's traffic.
  3. Records history for 95th-percentile billing, stats and streaks.
  4. Rolls failures (fireFailure()) and events (fireEvent()) when their timers run out, and expires incidents.
  5. Updates customer mood, churn and new offers; IX members join; loans tick.
  6. Every 30 days: bills the month (revenue minus costs) and checks for bankruptcy.
  7. Checks goals, level, badges and scenario end conditions.

compute(): the traffic model

  1. Builds a graph from your live links: parallel links between the same two cities merge into one edge with summed capacity. Link metrics set weights; Dijkstra gives shortest paths from each POP.
  2. Builds the exit list E: embedded caches (rank 0), PNIs (1), IX ports (2), transit (3). Each exit has a capacity, the networks it can reach (ok(net)) and an egress preference (high, normal, low = backup only).
  3. Builds flows: for every POP, its demand (eyeballs and customers) split across destination networks by their traffic share (NSH, with regional variants for China, Russia and Korea). Incidents can add junk flows or scale demand.
  4. Routes flows rank by rank: the nearest usable exit first, ECMP across equal exits, consuming link, router (nodeCap) and exit capacity. With Auto-TE, overflow spills onto alternate paths; RouteScript rules (teRules()) can prefer, avoid, cap, drain or blackhole.
  5. Layer-2 customers (L2VPN, SD-WAN, waves) are carved out of link capacity first.
  6. Totals costs (R.cost) and revenue (R.rev) per month.

It runs every day and after every action, so it is built for big networks: the graph works on city indices (CIDX), each exit is asked once per network what it can reach, and R.ef (what crosses each link) is only put together for a link when something reads it.

Served share per city (sfOf) drives eyeball revenue and customer mood.

Actions and rendering

  • Player actions live in ACT. Buttons render as btn(label, act, args, cls, disabled) and a delegated click handler calls ACT[act](JSON args).
  • An action validates its inputs (they come from the DOM), mutates S, shows a toast() and calls after().
  • after() = purgeInc() + compute() + checkGoals() + renderAll() + save().
  • renderLeft() draws the left tabs (deals, NOC, customers…), renderPanel() the selection panel (city, link, network). On phones these become bottom sheets controlled by renderTabbar().
  • These panels and the dashboard are rebuilt as HTML every tick and written with morph(), which patches only what changed. Buttons whose action changed are replaced, so taps stay safe (#44).
  • The map is a canvas drawn every frame by draw(). Zoomed out (lodFar()) it uses a simplified style; parallel waves are grouped by linkGroups().

Saves, imports and migration

  • save() writes S to localStorage every few seconds and after actions.
  • boot() loads the save through migrate() → sanitize(). If loading throws, the damaged save is kept under sot-save-broken and the player starts fresh.
  • sanitize(s) is the gate for all untrusted state (saves and imported files): it drops unknown ids, clamps numbers, repairs references and fills defaults. Every new field in S needs a line there.

Translations

  • tr(text, vars) looks up DICT[text] and fills {placeholders}; trn(one, other, n) picks the plural; N_(text) marks a literal for the checker and translates later.
  • Static markup uses data-i18n; i18nDom() swaps it at boot.
  • The English text is the key, so changing English text means updating the key in every dictionary.

Tests

tests/*.test.js use node:test and tests/harness.js:

const { load } = require('./harness');
const { ev, errors } = load();            // seeded, deterministic
ev("ACT.start({});S.cash=1e8;ACT.launchBB({city:'fra'})");
ev("compute()");
assert.equal(ev("R.reach>0"), true);
assert.deepEqual(errors, []);

ev() runs code inside the page. To force a specific random failure, patch the picker, e.g. evaluate fireFailure with .replace('const e=pick(opts);', "const e='x';"). Use window.__reseed(n) to reset the random sequence mid-test.