- docs/adr/0001: GitHub Pages is the only host, not open for renegotiation - docs/adr/0002: source in many files, shipped as one page assembled at build - tests/pages.test.js: builds stay static files Pages can serve, all local references resolve, only release.yml deploys and only via the Pages actions - tests/build.test.js: partial naming and layout rules - new skills: github-pages, edit-the-game; add-strings, performance, release and write-tests updated for src/, sorted dictionaries and --base-ref - CLAUDE.md, ARCHITECTURE.md, CONTRIBUTING.md (incl. porting older branches), README.md and the PR template describe the new layout
175 lines
11 KiB
Markdown
175 lines
11 KiB
Markdown
# Architecture
|
||
|
||
Series of Tubes is a static web game hosted on **GitHub Pages, and only there**
|
||
([ADR 0001](adr/0001-github-pages-only.md)). Its source is split into many small files under `src/`;
|
||
the build joins them into **one self-contained `index.html`** (one inline `<style>`, one inline
|
||
`<script>`), exactly the page players have always loaded ([ADR 0002](adr/0002-one-page-assembled-at-build.md)).
|
||
|
||
```
|
||
src/ the game page, in pieces
|
||
index.html shell: <head>, static markup, the language loader, two @include lines
|
||
styles/NN-*.css → pasted into the page's <style>, in path order
|
||
game/NN-area/NN-*.js → pasted into the page's <script>, in path order
|
||
site/ static files copied to the build as they are (dictionaries, icons, sw.js…)
|
||
scripts/lib/page.js the assembler: <!-- @include DIR --> → every file under src/DIR, sorted
|
||
scripts/build.js _site/ = site/ + the assembled page, version-stamped, release notes baked in
|
||
```
|
||
|
||
Because the partials are concatenated into one classic script, they share one top-level scope, just as
|
||
when they were one file: `S`, `CITY` or `compute()` are visible everywhere, function declarations are
|
||
hoisted across files, and top-level statements run in path order. Find code by name
|
||
(`grep -rn "function compute(" src/game`); the folders follow the game's layers:
|
||
|
||
| Folder under `src/game/` | What lives there |
|
||
| --- | --- |
|
||
| `00-core/` | `tr()`/`trn()`/`N_()` and the dictionary; version, release notes and the analytics counter |
|
||
| `10-catalog/` | Prices and gear: POP and port costs, routers (`RG`), supply chain, port slots, dark fiber systems and optics (`OPT`), reach and subsea upgrades |
|
||
| `20-world/` | Map projection, landmasses, coastline, city coordinates (`CITY_LL`), `CITIES`, `CABLES` |
|
||
| `30-networks/` | Other ASes (`NETS`), rival exchanges (`XIX`), the long tail, traffic shares (`NSH`) |
|
||
| `40-progress/` | Customer types (`BIZ_T`), `LEVELS` and their requirements, `GOALS` |
|
||
| `50-state.js` | The globals `S`, `R`, `UI`; `emptyR()` |
|
||
| `60-features/` | Banks and loans, scenarios and the weekly challenge, conferences, the tutorial, traceroute, the share card, `newGame()` |
|
||
| `70-rules/` | Formatting helpers and market rules: exchanges, PNIs, the peering inbox, peering policy and snubs, DE-KICKS, sold-out routes, hot ports and the Tier 1/2/3 rank |
|
||
| `80-simulation/` | Dijkstra, RouteScript, `compute()`, monthly prices, `sanitize()`/`migrate()`, customer requirements, events, geography pricing and latency, second sites and service |
|
||
| `85-incidents/` | `addInc()`, DDoS and scrubbing, `fireFailure()`, `clearInc()`, `fireEvent()` |
|
||
| `88-days/` | `dayTick()`, new offers, badges, `checkGoals()` |
|
||
| `90-actions/` | The `ACT` map, one file per area (`const ACT` in `10-interface.js`, `Object.assign(ACT,…)` in the rest), and their helpers |
|
||
| `91-save.js`, `92-audio.js` | Save, export and import; sound effects |
|
||
| `93-ui/` | DOM helpers (`$`, `btn`, `morph`), the phone tab bar, install pitch, HUD, left panel, city and link panels, decommissioning |
|
||
| `94-dashboard/` | Scenario and level progress, where to meet a network, customers and connections overviews, lease swaps, the NOC dashboard, the bank, hints |
|
||
| `95-modals/` | Toasts, notifications, modals, title screen, what's new, help, the link and own-cable modals |
|
||
| `96-map/` | The canvas: resize, land and clouds, settings, level of detail, link geometry, `draw()`, the world layer, cities, input and click delegation |
|
||
| `99-loop.js` | `frame()` and `boot()` |
|
||
|
||
`src/styles/` holds the CSS the same way: base, HUD, drawers, toasts, modal, tablet, then phone.
|
||
|
||
Rules for the source (checked by `tests/build.test.js` and the assembler): files are named
|
||
`NN-lower-case.js`/`.css`, end with a newline and never close their `<script>`/`<style>`; top-level code
|
||
may only use top-level values from earlier files; tables people add to have one entry per line, the
|
||
id-keyed ones sorted. New features get their own file in the right folder (`edit-the-game` skill).
|
||
Development runs on `npm run dev` (assembles on every request, reloads on save);
|
||
`npm run page -- -o FILE` writes the assembled page.
|
||
|
||
## Other files
|
||
|
||
| Path | What it is |
|
||
| --- | --- |
|
||
| `site/i18n/it.js`, `pt.js`, `fr.js` | Dictionaries: English text → translation, one entry per line, sorted; loaded only for that language |
|
||
| `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, `404.html`, `CNAME`, `robots.txt`, `sitemap.xml`, `llms.txt` | PWA and GitHub Pages files, copied as they are |
|
||
| `scripts/lib/page.js` | Assembles the page from `src/` (also from a git ref with `--ref`, for performance baselines) |
|
||
| `scripts/build.js` | Builds `_site/` for GitHub Pages: copies `site/`, writes the page, stamps `__VERSION__`/`__BUILD_DATE__`, bakes release notes, writes `version.json` |
|
||
| `scripts/dev.js` | `npm run dev`: development server, no dependencies |
|
||
| `scripts/test.js` | `npm test`: runs every `tests/*.test.js` |
|
||
| `scripts/release-notes.js` | Extracts a version's CHANGELOG bullets |
|
||
| `scripts/perf-bench.js`, `perf-browser.js`, `perf-stats.js`, `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`, `scripts/i18n-add.js`, `scripts/lib/dict.js` | Translation coverage and dictionary order; adding, renaming and removing entries |
|
||
| `scripts/legacy/` | The splitter that made `src/` from the old `site/index.html`, and `port-branch.js`, which carries older branches over |
|
||
| `tests/harness.js` | Loads the assembled 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, the only workflow that can |
|
||
| `docs/adr/` | Decisions: GitHub Pages only (0001), one page assembled at build (0002) |
|
||
|
||
## 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`, which assembles `src/` in memory, so tests
|
||
never run a stale build. `npm test` runs every file in `tests/`; a new suite needs no registration:
|
||
|
||
```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.
|