The solutions architecture behind Four Lights.
Four Lights answers one question quickly: which lunar south-pole landing site still works when a launch slips? The hard part is a horizon calculation over a hundred million terrain pixels per site. The architecture is built around doing that once, checking it properly, and making everything after it instant.
Overview
Three stages, with a hard line between them. Heavy computation happens ahead of time on our own machines. What it produces is a set of small static files. The browser does the final, cheap arithmetic, so every interaction is immediate and there is no server to scale.
flowchart LR
subgraph NASA["Open NASA data"]
LOLA["LOLA elevation models
5 m to 240 m, about 5 GB"]
HZ["JPL Horizons
Sun and Earth, hourly"]
SP["NAIF SPICE kernels
check and DSN stations"]
US["USGS Artemis regions"]
MT["Moon Trek map tiles
3D Moon imagery"]
end
subgraph PRE["Precompute: Python, our machines"]
FE["Fetch
SHA-256 pinned"]
HE["Horizon engine
720 directions per site"]
EP["Ephemerides
17,544 hours per site"]
PB["Publish"]
end
subgraph EDGE["Cloudflare: one Worker"]
AS["Static assets
12 site files, planner summary"]
WK["Hono Worker
pages, data, API"]
AI["Workers AI
question to settings only"]
DO["Durable Object
one per shared project"]
R2["R2 bucket
large rasters, computed sites"]
end
FL["Hosted machine
the pipeline in a container,
for a site someone adds"]
BR["Browser
four lights, planner, chart, map"]
AG["AI assistant
through MCP"]
QG["QGIS
reads the layers in place"]
LOLA --> FE
US --> FE
FE --> HE
HZ --> EP
SP --> EP
HE --> PB
EP --> PB
PB --> AS
AS --> WK
WK --> BR
WK -.-> AI
MT -.-> WK
WK --- DO
R2 --> WK
AG --> WK
WK --> QG
WK -.-> FL
FL -.-> WK
Design decisions and their trade-offs
- Precompute, don't compute on request
- A site's horizon takes one to two minutes and about 1.5 GB of memory. No request should wait for that, and Cloudflare's free plan allows a Worker 10 ms of CPU. So horizons are computed once per site, offline. The cost: the app ships with 12 curated sites. A site someone adds is computed the same way, by the same code, on a machine the Worker starts for it (see The pipeline).
- Static files, no database
- The published result is one JSON file per site (about 470 kB) plus an index. Files are cacheable, versioned in Git, diffable, and downloadable by anyone. A database would add a failure mode and nothing we need for 12 sites. The one stateful piece, added on the second day, is a shared project (see Working together).
- The browser does the maths
- Comparing a body's elevation with the skyline is a table lookup. Doing it in the browser means the time slider, the date slip and every toggle respond without a round trip, and the rules live in one tested module.
- A precomputed summary for the first screen
- The planner needs every site for every date. Loading all twelve site files cost about 1.2 MB on first view, so the build writes a 36 kB summary, generated by the same rule code the browser runs, and a test fails the build if the two ever differ. Site files now load only when a chart is opened.
- One Worker for everything
- Pages, data and every API route are served by one Cloudflare Worker with static assets. Every request passes through it, which let one secret keep the whole site, data included, behind a password until launch. Deleting that secret opened the site in seconds, with no code change and no deploy.
- A language model with no authority
- The plain-English box sends the question to a model that may return only four settings. The Worker validates each against an allow-list and the planner computes the answer. The model cannot produce a number the user sees.
The pipeline
One command rebuilds every published file from NASA's originals. Each step is a small Python module with a Makefile target, and every run is logged with its inputs, their checksums, the outputs and the run time.
flowchart TD F["fetch
original URLs, SHA-256 verified,
offline mirror as fallback"] S["site point
tile centre or region summit"] H["horizon
3 observer heights x 720 sectors"] E["ephemerides
JPL Horizons, SPICE fallback"] D["DSN visibility
Goldstone, Canberra, Madrid"] P["publish
data contract, 0.01 degree rounding"] PS["planner summary
built by the app's own rules"] R["site reviews
model writes, checker verifies"] C1{{"overlapping models agree?"}} C2{{"Horizons equals SPICE?
Earth azimuth matches longitude?"}} F --> S --> H --> C1 --> P E --> C2 --> P D --> P P --> PS P --> R
Reproducibility is designed in: dependencies are pinned, every input file has a recorded checksum, and the downloads were verified against NASA's servers, not just our mirror.
Where it runs
The same code runs in three places and gives the same files. On our own machines it built the 12 curated sites, and that stays the reference and the fallback: it needs nothing but the repository and NASA's files. In a container (one command, Docker or Podman) it runs on any machine with nothing else installed: built that way, Shackleton rim comes out identical to the published file. And on a hosted machine it computes a site that someone adds to a shared project, with no one at a keyboard.
sequenceDiagram
participant B as Browser
participant W as Worker
participant D as Durable Object (the project)
participant F as Hosted machine (pipeline container)
participant R as R2 storage
B->>W: Compute this site
W->>D: mark the site "computing", keep a one-time token
D-->>B: status, to everyone on the project
W->>F: start a machine: the point, the token, where to send the result
Note over F: NASA terrain on a volume. Horizon, ephemerides, publish. About 90 seconds
F->>W: the site file, with the token
W->>R: store it for this project
W->>D: mark the site "ready"
D-->>B: status, to everyone on the project
B->>W: GET the site file
Note over B: lights, chart and planner row computed locally, as for any site
The heavy work never runs in the Worker: it starts the machine and stores what comes back. The machine holds no secrets of ours, only a token that is good for one result. One site is computed at a time, a project can compute five and the whole site a hundred a day, which bounds the cost, and removing one setting switches the feature off without a deploy.
The horizon engine
The core algorithm, and the part with the most ways to be quietly wrong.
- The problem
- At the pole the Sun sits within a degree or two of the horizon, so a ridge 100 km away matters as much as a boulder 100 m away. The skyline needs fine terrain nearby and wide coverage far off.
- Nested terrain
- Six elevation models are stacked: 5 m per pixel at the site, then 20 m to 60 km, 60 m to 150 km and 240 m to about 650 km. Each point uses the finest model that covers it. About 100 million pixels are evaluated per site.
- True 3D geometry
- Every pixel becomes a 3D position on the Moon's sphere and is viewed from the site's local east-north-up frame. That handles curvature exactly and avoids the classic polar trap, where map north and true north differ by the site's longitude.
- Maximum over a sector, not a ray
- For each half-degree of direction the engine keeps the highest terrain anywhere in the sector. Casting single rays would miss narrow distant peaks and over-predict sunlight.
- The near field
- A test with a smooth dome showed that binning pixel centres under-read nearby ground badly: minus 22 degrees where the answer is minus 5.1. The terrain within about 400 m is now resampled to 0.5 m, and the dome comes out within 0.01 degrees.
- Bounded memory
- Large rasters are read in windowed strips, never whole, so a 3.4 GB mosaic runs on a 14 GB laptop at a 1.5 GB peak.
Serving and the edge
sequenceDiagram
participant B as Browser
participant W as Worker (Hono)
participant A as Static assets
participant M as Workers AI
B->>W: GET / and /data/planner.json
W->>A: fetch asset
A-->>B: page, 36 kB summary
Note over B: planner drawn, no further requests
B->>W: GET /data/sites/site.json (on opening a chart)
A-->>B: skyline + 2 years of hourly positions
Note over B: lights, chart, battery computed locally
B->>W: POST /api/ask (optional)
W->>M: question
M-->>W: date, slip, window, site
W->>W: validate each field
W-->>B: settings only
- Deployment
- One command checks formatting, lint, types and unit tests, refuses to ship fixture data, builds, and deploys. Production deploys come only from an up-to-date main branch; everything else goes to a preview URL.
- State in the URL
- Site, dates, window, observer height, view and even an adjusted power system live in the address, so any view can be shared or bookmarked and the server keeps no sessions. A shared project is the one exception, and it is opt-in.
- Accessibility
- Native controls, full keyboard operation with shortcuts and a help dialog, status never carried by colour alone, 4.5:1 contrast in both themes, and reduced-motion respected.
Working together: shared projects, AI assistants and QGIS
Three ways to use the same results with other people and other tools. Each one reuses the published files and the one Worker; none adds a second source of truth.
- Shared projects
- Share Project gives a group one address. Behind it is a Durable Object per project, found only by an unguessable id: there is no list of projects, no accounts and nothing to search. Each browser holds a WebSocket to it, so a change of site, date or slip appears on every open page at once. Every change, from a person or a program, goes through one function that validates it, so there is one set of rules. The sockets hibernate, so an idle project costs nothing.
- An MCP server for AI assistants
-
The same Worker speaks the Model Context Protocol at
/mcp. Given a project's address, an assistant can read the project, rank the sites for a date, read one site's figures, and change what everyone in the project sees, through nine tools. Its answers come from the same published files as the page, and its changes are the same commands the browsers send. The figures it quotes are the planner's, not its own. - The 3D map
- The Map tab draws the Moon with three.js, which is loaded only when the map is opened so the first screen stays small. NASA Moon Trek's image tiles are fetched through a route on our Worker and kept in Cloudflare's cache for a week, so NASA's server is rarely asked twice for the same tile.
- Open in QGIS
- The sites, verdicts, skylines and terrain are also published as map layers in cloud-native formats (FlatGeobuf and Cloud Optimized GeoTIFF) with a ready-made QGIS project. QGIS reads them in place, a few thousand bytes at a time, so nothing large is downloaded. Static assets do not answer byte-range requests, so the Worker cuts the ranges itself; three rasters too big to be static files are in an R2 bucket, which serves ranges directly.
- Keeping it open safely
- The site needs no login. The question box and creating a project are rate-limited per address at Cloudflare's edge, before the Worker runs. Computing a site is bounded differently: one runs at a time, a project can compute five, and the whole site a hundred a day. Request sizes, project sizes and the model's output are all capped.
How we know it is right
Validity was treated as an architectural requirement, not a final step. Each layer has an independent check.
| Layer | Independent check | Result |
|---|---|---|
| Horizon geometry | A second implementation with different mathematics (map library and spherical trigonometry) | Identical on 8 directions across all 6 models |
| Horizon geometry | Cases with analytic answers: bare sphere, dome, single-pixel spike, a peak due north | All pass |
| Terrain inputs | Heights compared where neighbouring models overlap | Median difference 0.06 m or better |
| Sun and Earth positions | JPL Horizons against NAIF SPICE | Agree to about a millionth of a degree |
| Orientation | Earth's mean direction against each site's longitude | Within 0.2 degrees at all 12 sites |
| Rules in two languages | The Python copy of the rules against the app's own output, every site and landing day | Agree across 8,700 cells |
| End result | Barker et al. (2021), NASA Goddard, Connecting Ridge 2024 to 2026 | Longest night within their range; our illumination a few points higher, and we say so |
Testing and quality
- Unit tests
- 123 for the front end and Worker and 49 for the pipeline, run before every commit and deploy. The code that computes or draws is the best covered: the light rules 96% of lines, the chart and the battery model 99%, the globe's maths 97%, the pipeline's geometry 100% and its horizon engine 86%. The page wiring is exercised by the end-to-end tests instead.
- End-to-end tests
- 42 Playwright tests drive the real page in Chrome against a local Worker: the demo scenario and the cost of a slip, every control and shortcut, the data pages, a shared project in two browsers, the files QGIS reads, and the password gate on a second Worker instance.
- A regression test for the demo itself
- The headline scenario (a three-day slip from 19 April 2028) is asserted against the real data, so a change that would break the demo fails the build.
- Static checks
- TypeScript in strict mode with checked array access, ESLint, Prettier, and Ruff for Python, in one command.
- Constraining the model
- Every AI-written site review is checked by code: any number not in the supplied facts, or a claim the facts do not support, rejects the draft.
Stack
- Precompute
- Python, NumPy, rasterio and GDAL, pyproj, spiceypy; GRASS GIS for a cross-check. Packaged as a container image (Docker or Podman).
- Front end
- TypeScript and Vite, no framework; hand-written SVG charts; about 27 kB of script over the wire for the first screen. three.js for the 3D map, loaded on demand.
- Edge
- Cloudflare Workers with static assets, Hono, Workers AI, a Durable Object per shared project, R2, a rate-limiting rule and a custom domain. The Model Context Protocol for AI assistants. A Fly.io machine runs the pipeline container for added sites.
- GIS
- QGIS, GDAL, FlatGeobuf, Cloud Optimized GeoTIFF and GeoPackage.
- Quality
- Vitest, Playwright, pytest, coverage reporting, ESLint, Prettier, Ruff.
- Repository
- Laid out as numbered stages, each with a written contract and an output folder, shared facts in one place, and one card per dataset, so that a person or a coding agent can find what a task needs without reading everything.
The team
Four Lights was built over one weekend for the NASA Space Apps Challenge 2026 by Steve Dalton and Matt Paine, team Make it So, Gold Coast, Australia: two developers with 30 and 20-plus years of experience.
Steve and Matt both love maps. They have worked extensively with GIS tools such as QGIS and PostGIS on Earth, but never on the Moon before this weekend.
They work at Refactor, a technology consulting company that has been delivering solutions for businesses across Australia for more than 15 years, and at Refactor Red, its research and development arm, which builds products for environmental monitoring, smart infrastructure and access control. Refactor is a contributor to the QGIS project, and has previously contributed funding to the LIDAR features within QGIS.
How we work
We use Agile principles throughout: test-driven development, pair programming, fast cycles and small batch sizes. This project ran the same way. More than 140 small commits went to the main branch over the weekend, each one checked by the unit tests before it landed, and the live site was redeployed after nearly every change, so there was always a working demo and never a big-bang integration.
What this project shows of how we work:
- Solutions architecture: putting the expensive work where it is cheap, and keeping the runtime simple.
- Geospatial and scientific computing: planetary coordinate systems, large rasters, ephemerides.
- Edge platforms: Cloudflare Workers, static-first delivery, constrained AI integration.
- Engineering discipline at speed: reproducible data, independent verification, tests that guard the demo.
- Honest reporting: stated limits, and a published comparison where our numbers differ from NASA's.
We used AI coding tools (Claude) to help write the code, tests and data pipeline; the idea, the design decisions and the checking of results are ours.