A drawn instrument: building Mars Deck

Mars Deck is a live map of the solar system with a countdown to the next Earth-to-Mars launch window. Every planet and 6,200 real asteroids are drawn where they actually are, right now.

The people who care about this kind of product check the numbers. So it had to be accurate enough to survive that audience, clear enough to share as a screenshot, and it couldn't depend on anyone else's service. Three decisions shaped it.

1. Compute it, don't fetch it

Most space apps fetch positions from an API. Mars Deck calculates them. Every position is solved in the browser from orbital elements, and launch windows come from a Lambert solver, the standard method for finding a transfer orbit between two points.

The real data, 6,200 small bodies from NASA/JPL plus five spacecraft, is downloaded once when the site is built and shipped as a static file. Drawing the map makes zero network calls.

What that bought:

• It loads instantly and works offline.
• No third party can break it by changing or retiring an API.
• The numbers can be checked. The transfer solver matches the textbook closed-form answer to five significant figures. Mars oppositions land within 0.8 days of the published dates.

What it cost: weeks of verification, and an accuracy ceiling the site has to admit openly. The about page says where the maths is approximate, and why.

Doing the maths also corrected something I had believed. People say Mars comes close "every 26 months". Measuring 116 oppositions between 1800 and 2050, the gaps run from 766 to 804 days. It's an average, not a rhythm.

2. Lines, not realism

At one point I tried drawing the planets more realistically: shaded surfaces, polar ice that followed the lighting. Each attempt was physically correct and looked broken.

Ice that stopped at the day/night line looked like a snowdrift on one side of the planet. Faint ice on the night side read as the brim of a hat. A boundary dimmed where the planet was in shadow looked like a half-drawn line.

The lesson was that a marking on a chart is not a surface. A contour saying "the ice reaches here" shouldn't fade in the dark, any more than a line on a map fades at night.

So Mars Deck stayed what it already was: a drawn instrument. Orbits are lines, the grid is lines, the navigator is lines. That also turns out to be the honest choice. What the engine computes is a boundary, and a line is a boundary.

3. When it breaks twice, question the architecture

I wanted you to be able to zoom from the whole solar system down to Mars. I built it, and the first report back was that Mars "drops away" when you spin it.

I patched it, and it came back. I patched it again, and again. Four patches, and each one created a new interaction bug.

The real cause was structural. The camera orbited the Sun. Zoomed in on Mars, every drag swung the view around a star 1.5 AU away, and Mars went with it. No patch could fix that.

The fix was to stop zooming. A planet gets its own page, with a camera that orbits that planet, in kilometres. A day of work went in the bin, and the result works. The Mars page is still in testing before it goes public.

When the same complaint comes back twice, stop patching and question the design.

Small things that weren't small

• A new page shipped black for returning visitors. Scripts are cached for seven days. The main page loads them with a version stamp in the URL, but the new page loaded one without, so returning browsers ran an old engine and drew nothing. Every page is now checked for stamps before deploy, and that check immediately found two other live pages with the same fault.
• Coordinates from memory were wrong. Checking eight Mars landing sites against a published source, three of the values I had were off, one by more than a degree. Now every coordinate has a source.

The AI part

Mars Deck has an assistant, Ask the Deck, which runs on xAI's Grok. It never does the maths. The engine computes the positions first and hands them over, and the assistant may not state a number it wasn't given. I wrote more about that in Why our AI can't make up numbers.

The full case study, with the decisions and their costs, is here.