danpune.github.io/timezones

Inside Time Zones

The whole site is one web page kept on GitHub. There is no server doing work in the background, no database and no app store. Your phone downloads the page and does every calculation itself. Here is how it all comes together.

Today in Austin, Texas, hour by hour. The site paints every hour with the colour of the real sky, worked out from where the sun is. This strip was worked out the same way, on your device, just now.

The big picture

Think of it like a recipe. GitHub keeps the recipe, GitHub Pages hands out copies, and your phone does the cooking.

Where it's kept

GitHub

The project is a folder of files stored on GitHub. Every change is saved with a note, so the full history is kept.

index.html
~110 KB
The whole app: the layout, the look and every calculation.
cities.txt
201 KB
About 6,300 cities with their map positions.
flags/
72 images
State flags for the US, Canada and Australia.
sw.js
2 KB
The offline helper.
manifest.json + icons
35 KB
Let it sit on a home screen like an app.
How it reaches you

GitHub Pages

GitHub's free web hosting. It hands those files to anyone who visits, over a secure connection.

https://danpune.github.io/timezones/

It never runs the code. It only delivers it, the same way for everyone.

Where it actually runs

Your phone's browser

What time is it there?
Answered by the time zone database built into your phone, the one the Clock app uses. Daylight saving rules come with it.
Is the sun up?
An astronomy formula turns each city's latitude and longitude into the sun's height for every hour. That gives sunrise, sunset and the sky colours.
Which cities did I pick?
Saved on this device. The link carries them too, like #Austin,London.
No signal?
The offline helper keeps a copy of the page, so it still opens.
Asks outside, when online
  • Open-Meteo for the weather, all cities in one request
  • hits.sh for the visit counter
  • Cloudflare for anonymous visit statistics, no cookies

The key ideaGitHub stores and serves files. Everything except the weather and the visit counts is worked out on your own phone.

One tap, start to finish

What happens in the second or so after someone opens the link.

  1. You open the linkYour phone

    The browser asks GitHub Pages for the page at danpune.github.io/timezones.

  2. The page arrivesGitHub Pages

    One file, index.html, about 110 KB. That's smaller than most photos, and it holds the whole app.

  3. It decides which cities to showYour phone

    Cities in the link come first. Otherwise, the ones you saved last time. Otherwise, Austin, San Francisco, New York, Mumbai and London, plus your own time zone if none of those match it.

  4. It asks the phone for each city's timeYour phone

    "What time is it in America/Chicago?" The phone's time zone database answers, with daylight saving already applied.

  5. It works out the sun and paints the stripsYour phone

    The sun's height for all 24 hours of each city's day, turned into colours from night blue through sunrise orange to day blue.

  6. It fetches the weatherOpen-Meteo

    One request covers every city. With no internet, each card keeps its sun or moon symbol instead.

  7. It saves a copy for next timeYour phone

    The offline helper stores the page, the city list and the icons, so the site opens even without a connection.

  8. It keeps the clocks movingYour phone

    Every 5 seconds it checks the time and redraws when the minute changes. Nobody needs to refresh.

The technical design

The same system, end to end, the way an engineer would draw it: how it is built and published, and what runs on the visitor’s device.

Technical design of the Time Zones siteData prep scripts produce cities.txt, embedded time zone tables and flag images. The developer commits and pushes to the GitHub repository danpune/timezones, and GitHub Pages publishes it over HTTPS. On the visitor’s device, a service worker with Cache Storage serves index.html. Inputs from the link, saved cities, gestures and search feed the page state. Engines for places, sun, weather, time and clock changes feed render(), which draws the cards and saves the state to the link and local storage. The time engine uses the operating system’s Intl API and IANA time zone database. When online, the weather engine calls Open-Meteo, a Cloudflare Web Analytics beacon reports an anonymous page view, and the footer loads a hits.sh visit counter image.BUILD & PUBLISH · DEVELOPER’S MAC AND GITHUBData prep, run onceGeoNames → cities.txtabout 6,300 cities, CC BY 4.0IANA tzdata → index.htmlzones, map positions, countriesWikimedia SVGs → flags/72 PNGs via headless ChromeDeveloper’s Mac~/timezonesedit and test on alocal web server,then git commitGitHub repositorydanpune/timezonesbranch mainevery change keptas a commitGitHub Pagesdanpune.github.iostatic files over HTTPS,republished on everypush, about a minutefilespushdeployVISITOR’S DEVICE · INSIDE THE BROWSERON THE INTERNETOnly asked when online.Weather requests carrycity map positions only.Service workersw.jspage: network firstfiles: cache firstother sites: left aloneCache Storageone cache per versionpage, cities.txt, iconsand any flags already seenOperating systemIntl · IANA tz databaseevery zone’s clock rules,updated by OS updatesLocal storagetz1 · tzPrefcities, base city, 12h/24h, °C/°Findex.html · one inline scriptLink#Austin,PuneSavedlocalStorageGesturestap · typeSearchcities.txtStateplaces · base city · time · 12h/24h · °C/°FPlacesname → zone,position, flagsplace()Sunheight each hour,−0.833° sunrisesunAlt()Weatherall cities, onerequest, hourlywxLoad()Timewall clock in each zone,safe across DST gapswall() · instantAt()Clock changesscan −7 to +14 days,bisect to the minuteclockChange()render()cards, 24-hour sky strips, overlap finder, clock-change noteSaved & sharedsave() · writeHash()link and storage followevery changeOn screenredraws when the minutechanges, checked every 5 sservesIntlsaveOpen-Meteoapi.open-meteo.comtemperature and weathercode by hour, 8 daysJSONCloudflareWeb Analytics beaconanonymous visit stats,no cookiesstatshits.shvisit counter badgeloaded as an imagein the footerimageHTTPS requests for the page and its files

Scroll sideways to see the whole diagram →

Always happens Only when online GitHub and the developer’s Mac Visitor’s device Internet services
One file, no build
HTML, CSS and JavaScript all live in index.html. No framework and no dependencies; any plain web server can run it.
State in the link
The address holds the cities, base city and any planned time, so a copied link opens the same view. Local storage keeps it between visits.
Time
Intl.DateTimeFormat reads the device’s IANA time zone database. Times that fall inside a daylight-saving jump are resolved by bisection, so the slider never runs backwards.
Sun
NOAA’s solar position formula gives the sun’s height. Sunrise and sunset use −0.833° to allow for refraction and the sun’s disc, cached per city per day.
Offline and loading
The service worker serves the page network-first and files cache-first. The offline helper saves the city list on the first visit; search reads it when you first type. Flags load only when shown, weather in one call.
Safety
Text from a link, a rename or storage is escaped before it reaches the page, and map positions in links are range-checked.

How a change goes live

Updating the site is saving a file and sending it to GitHub. There is no install and nothing to restart.

  1. EditChange index.html
  2. CommitSave it with a note
  3. PushSend it to GitHub
  4. PublishPages updates, about a minute
  5. RefreshPhones get it on next open

Each version is stamped at the bottom of the page, for example build 2026.09.12-k. When a phone opens the site and finds a newer version, the page reloads itself once to switch over.

Where the information comes from

Most of it is already on your phone or worked out there. Only the weather and the visit counts need the internet every time.

What you seeWhere it comes fromDownloaded?
Times and daylight savingThe time zone database built into your phoneAlready on your phone
Sunrise, sunset, sky coloursCalculated on your phone from each city's latitude and longitudeCalculated
Country flagsFlag emoji built into your phoneAlready on your phone
City searchGeoNames, a free world places database, packed into cities.txtOnce, on your first visit
State flagsPublic-domain images from Wikimedia CommonsOnly the ones shown
WeatherOpen-Meteo, a free weather serviceEach visit, online
Visit counterhits.shEach visit, online
Visit statisticsCloudflare Web Analytics: anonymous, no cookies, and only the page address without your citiesEach visit, online

Hosting costs nothing, and there are no accounts, ads or database. With no server running, there is nothing to keep switched on.

Words you'll hear

HTML
The language a web page is written in. It says what is on the page.
JavaScript
The part of the page that thinks: converts times, works out the sun, reacts to taps.
GitHub
A website that stores code and remembers every change made to it.
GitHub Pages
GitHub's free hosting, which turns a folder of files into a public website.
Service worker
A small helper the browser keeps for a site. Here it saves a copy so the page works offline.
Time zone database
The shared list of every region's clock rules, including daylight saving. Phones and computers update it for you.