How this is built

Where a request goes

The two sites are static files. Everything that needs a key, a database or a verified identity goes through the API.

Everything that needs a key, a database or an identity goes through the API: three of the upstreams need a credential, and a key in a page is a key anyone can read with View Source. The one thing that does not is the basemap. Map tiles are fetched one per square as you pan, so your browser asks OpenFreeMap for them directly. Forwarding a few hundred of them a session would mean running a tile server. Satellite on /f1/ is a second host on the same terms, EOX's Sentinel-2 composite, and it is reached only after the Satellite control is turned on. Those two are the only upstreams your browser contacts itself, so the diagram names them as the exception: their arrows would have to leave from the top of the picture, and every other arrow leaves from the bottom. The upstream list below says what that costs.

The three deployables

Two of them are built from the same repository by two Eleventy configurations that share one set of includes and one stylesheet, so both draw their chrome from the same implementation.

Where data lives

Four places, and they hold very different things. The weather, the departures and the Formula 1 data are not stored anywhere.

• Firebase Authentication

  Email addresses and password hashes. The browser trades a password for a signed token, and the API only ever sees the token. Deleting an account here is what actually stops somebody signing in; everything else is a record about them.

• Firestore

  One document per account: name, role, approval state, home location, home stop, favourite teams. The role is read from here on every single request. It is a separate store from the one above, which is why an account can exist with no document and why erasure removes both.

• Postgres

  Ten tables. Contact submissions, a row per process start, which migrations have run, and the one-row table holding the secret behind the visitor number below. Five the system writes for itself: the status page's health checks (seven days), the shape of each upstream's answers and what changed in it (field names and types, never a value), GitHub webhook deliveries that passed their signature check (30 days), and the sports data, saved so a restart does not fetch three leagues again. And one row per page view: path, which of the two properties, the referring host, the time, a coarse browser, OS, device class and width bracket, the country as two letters (looked up on the server from the address; IP geolocation by DB-IP, CC BY 4.0), and a visitor number that is a 64-bit hash of a 24-hour secret, the address, the User-Agent and the property. The server feeds the address and the User-Agent into that hash and stores neither. It cuts the referring URL down to its host, sets no cookie, and erases the number from the row after 30 days. The secret is replaced every 24 hours and the old one is destroyed rather than kept, which is what stops one day's numbers being matched to the next day's; it is the one thing in this database the data view will not show you. Browsable on the data view if you are an admin. A contact submission can be deleted one row at a time from Messages, or all of one person's at once by erasure.

• Memory

  Every upstream answer is cached in the API process for between 45 seconds and six hours, and lost on restart, except the sports data, which is also saved to Postgres. A bus or a race lives in memory and nowhere else, so there is no history of either to browse.

Until recently nothing in this system could take a person out of any of them. It can now: erasure takes one email address and removes that address's contact messages from Postgres, its account document from Firestore and its sign-in from Firebase Authentication, then answers with a receipt of what it actually removed instead of a success message. One action across three stores, because that is how far a person is spread: deleting from one leaves the other two still holding them.

There is a fifth place, and it is the honest part of this page. A message sent through the contact form is stored and emailed, so a copy sits in a mailbox and in the mail provider's delivery log. Neither is a store this code owns, and nothing in the endpoint list below reaches into them. The erasure preview and the receipt both say so, in the API's own words, so nothing reports a deletion wider than the one that happened.

Why the two sites count differently

The public site counts only after you say yes. The banner is opt-in, declining means nothing is counted at all, and that has not changed. What changed is only where the count goes: to the API above, not to a third party.

This app counts every page load, with no banner. It is behind a login, everyone here is an approved account holder, and counting loads of your own service for the running of that service is operational telemetry, not audience measurement. A row here carries the same visitor number the public site's rows carry, and on the same terms. The secret behind it is replaced every 24 hours, and the number is erased from the row after 30 days. The legal basis is different, so the consent is too. The line that keeps that honest is being told, which is what this paragraph and the privacy notice are for; a count nobody is told about would be the same count with the honesty taken out.

"Everyone here is a known account holder" has to be true of the code, not only of the intent, and for a while it was not: these pages are static files that anyone can fetch, and the sign-in is a redirect JavaScript performs once one has loaded, so a stranger opening /transit/ was counted on the way to being bounced. The beacon now fires from shell.js only after /me has confirmed the session, which is the earliest moment that sentence means anything. Not signed in, not counted.

Erasure does not reach this table, and an email address is not a handle it could be pointed at. A view row carries no account and no address. It does carry the number, which groups one browser's page loads inside a single day and stops there, because the next day's secret is a new one and the old one is gone. After 30 days the server erases the number and leaves the row as a path, a time and four coarse browser facts.

The endpoints

Every route the API serves, and the lowest role that may call it, grouped and folded away on a narrow screen. Each one re-reads your role and approval from Firestore before doing anything, because a token proves who signed in, not what they may do now.

Loading the endpoint list…

The upstreams, in detail

Ten of the eleven are called by the server. Three of those need a credential, which has to stay on the server; the rest so that one call serves every reader, and for the three sports sources, so a page reads a saved copy rather than three unofficial sites. The eleventh is the basemap, and it is not proxied at all: your browser fetches its tiles itself, which makes it the only one your browser has ever heard of. ESPN, shl.se and hockeyallsvenskan.se share one entry below, because they do one job, and so do the two papers. Each one below lists what is called, how long an answer is held, and how their field names become ours.

In the mapping tables, theirs is on the left and ours on the right. A row marked derived is something nobody sent: it is worked out here, and those rows are the decisions, not the transport.

The two credentials are read from the environment on the server and stay out of every response, error message and log line. Upstream errors are reported by status code only, because an error body can echo the request back, and the request carries the key.

Rules the code follows

Each of these is here because breaking it caused a real bug in this codebase.

• Check the type before coercing a number. Number(null) is 0, Number([]) is 0, and a query string can produce an array without being asked. Every parser guards on typeof first.
• An unknown role is the lowest role. Role names are an explicit list, not case-folding. Anything unrecognised resolves to the most restrictive answer.
• A comment may not claim a control the code does not have. If the code cannot be made true, the comment changes in the same commit.
• A signal that was never about the thing being checked proves nothing about it. A green test suite that never loads a module says nothing about that module.
• Never invent data on a dashboard. A panel with no source behind it says so.