← Bumpy Blog
Topic
iOS, SwiftUI, on-device scoring
Published
November 2026
Reading time
20 min
Companion post
Serving a turbulence forecast for any flight, to every phone, every hour
Drag across the picture to fly the route
Tokyo to San Francisco, scored on the phone from a real forecast run (30 October 2026) and graded for a mid-size jet. That run had no data below 10,000 ft, so the picture starts there.

01Why score on the phone?

Bumpy tells a passenger how bumpy a flight should be, minute by minute and at every height. Give it a flight number and a date, or two airports and a departure time. Back comes a grade for each stretch of the flight, in four bands: smooth, light, moderate or severe.

The picture above is the whole answer for one flight. We call it the curtain. Time runs left to right and height runs bottom to top. Each square of colour is the forecast for that height at that moment, and the dark line is the flight's own path through it.

Most apps would ask a server for that answer. Ours usually asks for the ingredients, a route plan and a list of forecast files, and the phone works out the answer itself.

The reason is the flights nobody asked about yet

Once an hour the server scores the flights it already tracks. But anyone can type any flight number, or any two airports, and most of those arrive with no score waiting.

Scoring one on the spot isn't much arithmetic. It's a lot of reading: up to a megabyte of forecast for a long route. We wanted the part of the server that answers every request to stay small, so it plans the route and stops there. The forecast is published as plain files, the same files for everyone crossing the same patch of sky that hour, and the phone does the reading.

It isn't about speed. The scoring itself takes about a millisecond.

What it costs

Two scorers. One in Python on the server, one in Swift on the phone, and a flight has to read the same whichever one ran. Keeping them equal, down to how each language rounds 47.25, turned out to be the most interesting part of the app. It has its own section.

Figure 1. Two ways a score reaches the screen
Arrows point the way the data travels. If the hourly job has already scored the flight, the plan arrives with the score and the files are never fetched. Either way the phone ends up holding the same kind of score, so nothing after this point knows which path ran.

02App architecture

The app is written in SwiftUI for iOS 26, in Swift 6, with the main actor as the default isolation. There's no login. There's no API key in the binary either: the one secret, the key for flight data, stays on the server.

The simplest way to see how it's put together is to follow one forecast through it.

  • Networking fetches the server's answer and the forecast files.
  • A scoring package turns them into a score.
  • A layer of plain Swift, with no interface code in it, turns the score into what a passenger reads: segments, status lines, the plane's position, the height of the sun.
  • The screens draw what that layer hands them. They decide nothing.

Two things about that split matter later. The scoring package lives in the backend's repository, so the Swift scorer sits next to the Python it copies. And because nothing below the screens touches the interface, most of the app can be tested without a simulator.

Refusing what it can't read

Two version numbers guard the border with the server: one on the forecast answer, one on the layout of the forecast files. A build that meets a newer number than it knows doesn't guess. It stops and says the forecast needs a newer version of the app. A half-read forecast would be worse than none.

03Sampling a tile

Those forecast files need describing before anything else makes sense.

The backend's forecast is a grid laid over the whole globe, with a value every quarter of a degree. Each value is in eddy dissipation rate (EDR), the standard aviation measure of how strongly the air is churning. We'll call one of those values a grid point.

The grid is cut into squares of 10° by 10°, called tiles. One tile holds every flight level over its square for one hour of forecast. That's the hour the forecast is for, not the hour it was made.

41 × 41
grid points on each level
22
levels, 1,000 to 45,000 ft
36,982
bytes in a tile

Each grid point is one byte, with 255 meaning no data. Each tile also repeats the edge it shares with its neighbours, so a point near a tile's border never needs the tile next door and the tiles a route needs can be listed in advance.

How the grid is built, and why the files are laid out this way, is in Serving a turbulence forecast for any flight, to every phone, every hour, under Grid and tile format.

Reading a value between the grid points

A plane is almost never exactly on a grid point, on a level, on the hour. So the sampler blends its neighbours along three axes, and has one rule for gaps:

  • Position. The four nearest grid points form a square, which we'll call a cell. The reading is a blend of its four corners. This is the step Figure 2 lets you try.
  • Height. A straight-line blend between the two nearest flight levels.
  • Time. The same, between the two nearest forecast hours. Very long routes use the nearest hour only, which halves the download.
  • Gaps. Corners marked 255 drop out and the rest are re-weighted. If what's left carries under a quarter of the weight, the point has no reading at all.
Figure 2. Blending the four corners of one cellDrag the point
Each corner counts for as much as the rectangle opposite it, drawn in the same colour: move toward a corner and its rectangle grows. With three corners missing, the reading survives only while the point stays close to the one that's left. The four values are made up for the example.

04Loading a forecast

Loading a forecast is one function. It asks for the forecast, decodes it, and takes one of two branches. If the answer already carries a score, that's the end of it. If not, it fetches every tile the plan lists, all at once, and scores on the phone.

The server's half of that first request, what it looks up and what it keeps, is in Serving a turbulence forecast for any flight, to every phone, every hour, under Request flow for a flight lookup.

A tile request is a plain download of a file that never changes once it's written, which is exactly what a cache is good at. Where the tiles are stored as slices of one bigger hourly file, the request asks for just its slice. If something in between ignores that and sends the whole file, the app cuts out the right bytes anyway. That's a bigger download. It isn't a failure.

Figure 3. One forecast load, timedMeasured from a server, not a phone
Timed against the live service on 17 November 2026 from a server in a data centre, so expect the two network rows to be slower on a phone. Each bar is the middle of 10 to 12 tries, and the thin line under it runs from the fastest to the slowest. The forecast requests were for routes the server hadn't planned before. Scoring is the app's Swift code, timed on the same kind of server. The waits are the app's own rule. The failed tries themselves weren't timed and aren't drawn.

What went wrong the first time

For its first few days the app ran only on forecasts bundled inside it. The day we pointed it at the live service, forecasts started failing. Not always. Mostly on the first load after a quiet spell.

The cause was on the server. A freshly started copy has to read the index of the current forecast before it can answer anything. It was noting that it had checked the index before the read had come back. Any request that landed in that gap was told there was no forecast, and got a 503. And the phone doesn't send one request. It sends dozens at once.

Worse, the app treated a tile like any other request: one failure, and the whole load failed. So a single unlucky tile out of thirty threw away the other twenty-nine.

Both ends were fixed the same morning. The server now makes a request that arrives mid-read wait for the answer. And the app tries again after any 5xx: it waits 400 ms, then a second, then makes one last attempt. Switch Figure 3 to a 503 to see what that costs. It's a little time, against a forecast that used to be lost.

05Route scoring on the device

The server's route plan is a list of timed points. Each has a position, a flight level and a phase of flight. The phone samples EDR at every one and turns it into a band for the flight's aircraft.

How long is each band? Every point stands for half the time back to the point before it, plus half the time on to the next. Add those up and you have minutes per band. The same pass produces four more things:

  • Stretches. The unbroken runs of points at or above each band.
  • The headline. The worst band that lasts at least five minutes and at least two points in a row, so one noisy reading can't set it.
  • Coverage. The share of flight time that has any reading. Under half, there's no headline at all.
  • The curtain. EDR at every level above every point: the picture at the top of this post.
Figure 4. Five real routes, and one with tiles missing
Each bar is one point of the plan, and its height is the EDR there. The dashed lines are where light and moderate begin for a mid-size jet. In the last case the gaps are points with no reading. Coverage falls below half, so the app shows no headline.

None of this is slow. On the longest test route, Singapore to London with 150 points and 28 tiles, the Swift scorer takes about a millisecond on the server we timed it on. We haven't timed it on a phone. A test fails if it ever takes more than 100 ms.

06Pilot report adjustment

The forecast is a model. Pilot reports (PIREPs) are what crews actually felt. So the forecast answer carries the recent reports near the route, and the scorer uses them in one direction only: to raise a reading, never to lower one.

How much does one report count? Its weight at a route point is three fall-offs multiplied together. Each is a straight line down to zero:

  • Distance. Gone by 100 km from the route point.
  • Height. Gone 4,000 ft outside the layer the pilot reported.
  • Age. Gone after two hours.

The reading then moves toward the report's EDR by that weight.

Figure 5. How much one report countsExample values
A forecast of 0.12 and a report of 0.40, moderate chop for a mid-size jet. Reports up to 30 minutes in the future still count, because the plan's times are estimates.

It matters. One test case is Los Angeles to New York scored twice from the same tiles: once with no reports, once with five real ones. The headline goes from light to moderate, and about 7 minutes of moderate and 3.5 of severe appear that the forecast alone didn't show.

And where the forecast has no reading at all? A single report can supply one, but only if its weight is at least a half.

07Aircraft size classes

EDR describes the air, not the cabin. The same air shakes a Cessna far more than an A380. So where each band begins depends on the aircraft, in five size classes. The server picks the class from the flight's aircraft type and writes it on the route plan. If it doesn't know the type, it says medium.

A mid-size jet turns light at an EDR of 0.10, moderate at 0.22 and severe at 0.34. A heavy such as a 777 needs more: 0.12, 0.27 and 0.42. Super is the A380 alone, about 5% gentler again. That last step is a judgment call. We didn't measure it.

Figure 6. The same air, five aircraft
Drag the EDR. At 0.24 a mid-size jet is in moderate, while a 777 is still in light.
Figure 7. Real routes, rescored for their aircraft
Each pair is the same tiles and the same plan, scored with two size classes. These are test cases the phone must reproduce exactly.

08Matching the Python scorer

The server scores in Python. The phone scores in Swift. If they disagreed, the same flight could read "light" one hour and "moderate" the next, depending only on who did the sums. So the Swift port is held to Python's output by tests, field by field.

The maths was the easy part. The hard part was every place the two languages do arithmetic differently:

  • Rounding. Python rounds the exact binary value, and sends a tie to the even neighbour. The obvious Swift version multiplies by 1,000, rounds and divides, and the multiply can push a value across the halfway point.
  • Floor division and remainders. Python's results take the sign of the divisor. The port re-implements both, edge cases included.
  • Sorting. Python's sort keeps equal items in their original order. The port sorts on the original position too, wherever ties can occur.
  • Searching a sorted list. A value that lands exactly on a grid level has to pick the same side in both languages, so the port carries its own search.
Figure 8. Where a value exactly halfway lands
  • Python, and the Swift port. A tie goes to the neighbour whose last digit is even.
  • Multiply, round, divide. The obvious Swift version sends a tie upward, one step off.
All four values are exact in binary, so each really is a tie. One step is enough to change a number a passenger reads.

Does one step matter? Minutes per band are shown to one decimal place. A flight with 47.25 minutes of light bumps has to say 47.2 on the phone, because that's what the server says.

The tests use twelve golden cases: real forecast tiles, real route plans and the scores Python computed from them. Five are plain routes. One adds pilot reports and one takes tiles away. Five more rescore a route for a different aircraft.

How closely the two must agree depends on the field:

  • What people read (headline, summary, stretches, minutes, coverage) must be exactly equal.
  • The curtain must match byte for byte. It uses no pilot reports, so no trigonometry.
  • EDR at each point may differ by 0.001. Pilot-report distances use sine and cosine, which can differ in the last bit between platforms. On Linux they don't: all 1,168 readings across the twelve cases come out identical.
  • Tiles needed must equal the tiles the sampler actually reads. A missing tile would silently become missing data.

The booking-text parser gets the same treatment: one shared file of cases that both the Python and the Swift parser must pass.

09From score to sentences

A score is numbers. The flight screen needs a sentence, like "Smooth now · light bumps in 1h 12m". That translation lives in one type with no interface code in it, which we call the flight story.

It works in two steps. First it merges neighbouring points of the same band into segments. A lone point that would make a sliver under five minutes is folded into its neighbour, the same idea as the headline rule that ignores one-point blips. Then it writes the sentences.

It never names a place. The app describes a flight only by phase: climbing out, early, mid and late cruise (the cruise cut into equal thirds), and descent. The server's plan does carry phrases such as "over the North Pacific". The app doesn't read them, and a test fails if one ever turns up in its text.

Figure 9. Status line along a real flight
Tokyo to San Francisco, medium-jet grades. Folding cuts the bar from segments, so the line doesn't flicker as you scrub across one-point blips.

10Flight screen layout

There's one flight screen. No tab bar. A full-screen satellite map sits behind everything, with the route drawn in the colours of its bumps and the plane on it. Across the top runs a 44-point header: back, a route pill that doubles as a progress bar, and a button for the full interactive map.

The forecast lives in a sheet with two resting heights. At medium, the map stays bright above it. At large, the sheet covers the screen and the map falls back. Four details made this harder than a stock sheet:

  • The map never moves. It's a fixed backdrop that ignores touches, framed once so the route sits in the part of the screen the medium sheet leaves open.
  • The screen behind recedes. The system doesn't push the screen back under this kind of sheet, so the app does it. On every frame, mid-drag or mid-spring, it reads where the sheet is actually drawn and scales the screen to match.
  • It's a transform, never a resize. Resizing the map would reset its camera. Scaling it doesn't.
  • The sheet can't be swiped away. Back closes the screen, so there's only one way out.
Figure 10. Dragging the sheetDrag the sheet
At medium the sheet's top sits at 47% of the screen's height; at large, at about 6.5%. In between, the screen scales linearly from 100% to 92% and its corners round to 55 points.

The map uses satellite imagery with realistic elevation, which draws the Earth as a globe. That's partly taste and partly need: a flat map can't zoom out far enough to frame a long-haul route. Satellite imagery also carries no place labels, and the standard map can't hide its own.

11Scrubbing: plane position and sky

A bar chart of the flight's bumps floats at the bottom of the screen, on Liquid Glass, with a plane for a thumb. Drag it and three things follow. The plane moves along the map. The status line changes. And the sky over the map shifts to the time of day at that moment.

None of it waits on a network. The score is already on the phone, so every frame of a drag is arithmetic on numbers it holds.

The plane's position comes from blending between plan points, going the short way round at the date line. Its heading is the bearing to the next point.

The sky comes from the sun. The app works out how high the sun is at the plane's position and time, using NOAA's simplified solar formula, which is good to about a degree. That takes no network and no location permission. Below the horizon the map gets a night wash. Within a few degrees of it, a sunrise or sunset glow.

Figure 11. Scrub a real flightDrag the plane
Tokyo to San Francisco on 31 October 2026, taking off in the Tokyo afternoon. The sun sets about an hour and a half in, the Pacific crossing is in darkness, and the sky starts to glow again near the California coast. Night wash and glow are the two tint strengths the app applies, each from 0 to 0.5.

The chart is capped at about 60 bars for the whole flight, never closer than three minutes apart, so a long-haul chart stays readable. Bars behind the thumb are in full colour and bars ahead are faded. Each time the thumb crosses into a different band, the phone gives a light tap.

12Live position

Before takeoff, the plane on the map is an estimate from the plan. Once the flight is in the air and public receivers can see it, the app shows where it really is.

It finds out by asking. While the flight screen is open and the app is in front, it polls the server for the flight's track every 30 seconds. Only inside a window, though: from 45 minutes before the gate departure to 45 minutes after arrival. A failed poll just waits for the next one, so going offline is quiet.

Figure 12. When the app polls
Timeline of the Tokyo to San Francisco flight. The solid bar is the time in the air.

The map also says where its line came from, in small text above the sheet: a filed route, a likely North Atlantic track, the route flown recently, or an estimated great-circle path. A live plane gets a filled marker, and the path it has flown is drawn solid on top of the forecast line. If the last fix is over two minutes old, a "Last seen" time appears. Live positions come from community receivers whose licence asks for credit, so the credit shows whenever live data is on the map.

13Adding a flight and parsing bookings

Adding a flight asks one question at a time, under a boarding pass that fills in as you answer. Where from? Where to? Which day? Then it lists that day's real flights to tap. A connection gets a second list, limited to departures 35 minutes to 20 hours after the first leg lands.

There are two shortcuts. Type a flight number and it jumps ahead. Paste a booking confirmation and it fills in what it can, then jumps to the first question still unanswered. A flight that isn't listed falls back to its takeoff time and an estimated route.

Booking text never leaves the phone. The shared parser reads it on the device. And the paste goes through the system paste button, which reads the clipboard only when tapped and shows no permission prompt.

Figure 13. The booking parser, running in this page
A JavaScript port of the same rules, checked here against the shared test cases. Edit the text. A known-airport list stands in for the app's bundled one. Two-letter words like OK, TO and FL are never read as airlines.

14Saved flights and offline use

Saved flights live on the device, in SwiftData. Each keeps its last forecast exactly as the server sent it, plus its score. So the list appears at once on launch. A flight is refreshed only when its forecast is missing or more than 15 minutes old, and a failed refresh keeps the old one.

Every milestone of the flight (gate out, takeoff, top of climb, top of descent, touchdown, gate in) is stored as an absolute time. That's deliberate. In the air the phone is usually offline, and it can still count down and show progress from the clock alone.

Works with no network

  • Saved flights and their last forecasts
  • Countdown, progress and the plane's estimated position
  • Scrubbing, status lines and the sky tint
  • Parsing a pasted booking

Needs a network

  • Refreshing a forecast
  • Live position and the path flown
  • Listing a day's flights to add one
  • Map imagery for areas not already loaded

The app also states its confidence in plain words. High when forecast data covers 90% of the route or more. Medium from half. Low below that, and low whenever the run fell back to the rough wind-only estimate. Confidence here means coverage. It doesn't mean weather models agreeing with each other.

15Testing and accessibility

Because the story, the flight picker and the scorer are plain types with no interface in them, most behaviour is covered by unit tests: decoding, refusing a newer schema, the golden routes, phase labels, bump grades, the connection maths and the no-place-names rule. One interface test drags the sheet from rest to half to full and back, at the default text size and at the largest accessibility size.

For VoiceOver the scrubber is a single adjustable element. A swipe up or down moves it by a twenty-fourth of the flight, and never less than five minutes. Each stop is read out as a short phrase.

Figure 14. The scrubber, as VoiceOver hears it
Tokyo to San Francisco is just under 10 hours, so each swipe moves about 25 minutes.

16Limitations and failure modes

The app's weak spots sit in three places: the forecast it's handed, the score it works out, and the map it draws on. The biggest one is upstream: thunderstorms.

Figure 15. Where each limitation sits

In the forecast

The forecast grid has no storm input. Thunderstorm turbulence shows up only through nearby pilot reports. Outside the regional model, the backend falls back to a rough estimate from winds alone, and the app says so with a note and low confidence.

There's a seam at the top of each hour, too. For a short while after a new forecast replaces the old one, a phone holding the old plan can ask for tiles that are already gone. The app treats that as a failed load.

In the score

With under half the route covered there's no headline, and the app says forecasts are still arriving. A headline built from a fraction of the flight would mislead. An unknown aircraft is graded as a mid-size jet. And a point reading may differ from Python's by one rounding step on a platform whose sine and cosine differ in the last bit. The tests allow 0.001.

On the map

Very long routes don't fully fit. Singapore to London sits with both ends at the screen's edges, because the globe is already at its furthest zoom. And the standard map style shows Apple's place labels, which can't be hidden. That's one reason satellite is the default.