Design the geolocation half of Tinder or Bumble
"The interesting thing about dating geo is that almost nothing about it is a hard real-time problem. A location fifteen minutes old is perfectly good, because nobody's dating radius moves in fifteen minutes, and that single fact makes the write path lossy, unordered and cheap. What is actually hard is three things: density varies by four orders of magnitude so a fixed radius is wrong at both ends, a circle is not a cell so the index over-fetches and then measures, and exact distance is a coordinate, which means the number that makes the product work is also the number that can find someone's apartment."
Understanding the problem
5 minFunctional Requirements
- A user's location should follow them as they move, without draining the battery.
- A user can set their location to another city (travel mode), and it replaces the device's location until it expires.
- A user should get a deck of nearby candidates that respects their distance preference.
- The distance shown should be useful to a dater and useless to a stalker.
- It should work in Manhattan and in rural Montana without two different systems.
Below the line (out of scope):
- Swipes and mutual matching. It is a like write plus a reciprocal check, it is cheap, and it never touches geo. Cutting it explicitly is what buys the time to go deep on the part that was actually asked about.
- Recommendation ranking and the ML behind who appears first. Geo produces the candidate SET; ranking orders it, and that is a different hour.
- Chat, photo storage and moderation, payments and boosts.
Non-Functional Requirements
- About 2,300 location writes, 1,200 deck builds and 11,500 swipes a second. The three rates are not close to each other.
- Inputs: 10M daily users, each making about 20 location writes, 10 app opens and 100 swipes a day, over 86,400 seconds a day.
- Location writes: about 2,300 a second. Small.
- Deck builds: about 1,200 a second. This is the only expensive read in the system.
- Swipes: about 11,500 a second, ten times the deck rate, so a swipe cannot afford any geo work.
- The shape of the answer falls out of that: the expensive thing happens 1,200 times a second, so it can afford to be clever.
- Manhattan is about 28,000 people per square kilometre. Rural Montana is about 1.8. That is four orders of magnitude.
- A 5 km circle covers 78 square kilometres either way: about 2.2M people in one and about 140 in the other.
- One fixed radius therefore returns a crowd you throw away, or an empty product. Both are failures.
- A location fifteen minutes old is fine, and that staleness tolerance is what the whole design spends.
- Nobody's set of plausible dates changes because they walked three blocks.
- So the write path can lose updates, reorder them, and lag, and none of it matters. That is unusual and it should be stated as a decision rather than assumed.
- The contrast worth drawing: a ride-hailing app needs your position to the second, which is why its design looks nothing like this one even though both are "geospatial".
- Population density spans four orders of magnitude, so one fixed radius cannot serve both city and countryside. It is the requirement people forget, and it is the one that breaks naive designs.
- Deck latency p99 under about 300 ms. It is the app-open path, so it is the product's first impression and there is nothing to hide it behind.
- Precise distance is a coordinate in disguise, so distance precision is a safety requirement. Safety is a functional requirement wearing a non-functional hat, and dating apps have been trilaterated in the wild. The precision of the number is a safety decision, not a UX preference.
- Consistency requirements are close to nil, and saying so is worth a sentence: there is no correctness problem if two users see slightly different distances, or if someone appears in a deck moments after going offline.
Entities + API
5 minDefining the Core Entities
- User is the profile plus the preferences that bound every query:
maxDistanceKm, age range, anddiscoverable. The discoverable flag is load-bearing, because turning it off has to remove someone from the index rather than filter them at read time. - Location is the latest fix only, overwritten on every write:
userId,lat,lon,cellId,lastSeenAt. No history is kept, and the coordinate never leaves the server.- Storing a location trail is a product decision nobody asked for and a liability everybody inherits. If it is not needed, not keeping it is the design.
- GeoIndex entry is the index itself:
cellIdto a set of user ids. That is the whole structure, and it is small: 10M users at a few tens of bytes is under a gigabyte. - Deck is the list of candidates a user swipes through:
userIdto an ordered list of candidate ids. - ExclusionSet is who this user has already seen. It grows forever and is checked on every deck build, which makes it a real data-structure decision rather than a footnote.
API or System Interface
POST /v1/location // { lat, lon, accuracy } -> 204, no body
GET /v1/deck?cursor= // -> { candidates: [ { userId, photos, bio,
// distance: "under 2 km" } ], cursor }
PUT /v1/preferences // { maxDistanceKm, ageRange, discoverable }
POST /v1/travel // { cityId } -> sets an explicit location, in scope as a constraint
- The location write returns 204 with no body, because nothing reads its own write. That is a design statement: there is nothing useful to return, and an empty response keeps the cheapest call in the system cheap.
- The deck returns a DISTANCE STRING, not a number. "under 2 km" cannot be trilaterated; "1.2 km" can. Making it a string in the response shape means no client, no analytics event and no debug view can accidentally leak precision later.
- No endpoint anywhere returns another user's latitude and longitude. Say it as an invariant, because the leak is usually not the main endpoint: it is a debug field, an analytics payload, or a photo's EXIF data.
- The deck is cursor-paginated, not offset-paginated, because the underlying candidate set is changing under you and an offset would skip and repeat people.
- Preferences are a write, not a query parameter, so the deck builder reads them from the user rather than being handed them at read time.
High-level design
10 min, end to end, no dives yet1) Location follows the user
- The client sends a fix as the user moves. How often the phone reports, and on what signal, sets both the battery cost and the write rate; the dive on moving users settles it.
- The write is fire and forget. 204, no body, no read-your-writes, no ordering guarantee. If two updates arrive out of order the loser is a location from four minutes ago, which is inside the staleness budget anyway.
- All the service does is move a user between cells and stamp
lastSeenAt. The new fix overwrites the old one; no trail is kept. - Travel mode is the same cell write, with the cell taken from the city the user picked (
POST /v1/travel) instead of from the device.
2) The index: cells, not radii
- The index is a map from cell id to a set of user ids. Geohash, S2 or H3 all give you the same shape; what matters is that a cell id is a prefix-comparable key, so "everyone near here" becomes a set of key lookups rather than a scan.
- A nearby query is a prefix read: everyone whose cell shares a prefix with the user's own, at a cell size about as wide as their distance preference.
- A cell is a square while the distance preference is a circle, and two people forty metres apart across a cell line share no prefix; the dive on finding nearby users handles both.
3) Building the deck
- The deck builder makes a page of candidates on each request.
- It reads the user's preferences, reads nearby users from the index, and drops anyone in the user's ExclusionSet or outside their age range.
- It returns about twenty candidates and a cursor, and the client asks for the next page as the user swipes.
- Each swipe adds that candidate to the ExclusionSet, so nobody is shown twice.
- The same query runs in Manhattan and in rural Montana, with the user's distance preference as the radius. One system, as the requirement asks.
- That radius holds a crowd in Manhattan and can come back empty in Montana; the density dive handles it.
- Every page is another spatial query, so a heavy swiper keeps the index busy; the dive on the deck handles it.
4) The distance on each card
- The deck builder computes each candidate's distance on the server and returns it as a string such as "under 2 km". No response carries a coordinate.
- Precision is the vulnerability, not the distance itself. A dater needs to know roughly how far; they never need two decimal places.
- Whether a rounded distance holds up against someone who can move and ask again is the trilateration dive.
Potential deep dives
~20 min, interviewer steers1) What actually answers "who is near me"?
WHERE lat BETWEEN ? AND ? AND lon BETWEEN ? AND ?- A B-tree on latitude and a B-tree on longitude cannot be used together: the database picks one, gets a band across the planet, and filters the rest by hand.
- At 10M rows and 1,200 queries a second that is a scan per query and the database falls over.
- It is also wrong at the poles and across the antimeridian, which is a smaller problem but the same root cause: latitude and longitude are not a plane.
- Encode the position as a geohash and match on a prefix, which is exactly what Redis GEO does with a sorted set underneath. This genuinely works and it is the right family of answer.
- Two gaps, and an interviewer will find both. A prefix match silently misses the neighbouring cells, so people forty metres apart never meet.
- And the cell size is fixed globally, which is the density problem: one level cannot serve Manhattan and Montana.
- Turn the circle into a covering set of cell ids and read the union. S2 and H3 both do this properly; H3's hexagons have the pleasant property that all six neighbours are equidistant, which removes a class of corner cases.
- Always include the eight surrounding cells, or two users either side of a cell line never see each other. This is the boundary bug, it is invisible in testing because your test users are never forty metres apart across a line, and it is the single most common defect in this design.
- Then filter by exact haversine distance on each candidate's stored latitude and longitude, so the index only has to return a superset. Haversine on a few hundred candidates is microseconds, so the index only has to be a good superset, never a precise answer.
- Keep the whole index in memory, because 10M users at about 32 bytes each (cell id, user id, latitude, longitude) is about 320 MB, well under a gigabyte. At that size this is a Redis-shaped problem, not a database-shaped one. That number is what makes the rest of the design affordable.
- Shard by cell prefix so a region's users live together and a query touches one shard. The natural consequence is that dense regions get hot shards, which is the next dive rather than a surprise.
- Cell size is the tuning knob: coarser cells over-fetch more with fewer lookups, finer cells waste less but read more neighbours. Pick per density rather than globally, which the density dive does.
- Choose the cell level coarser than your GPS error. An urban fix can be 50 metres off, so indexing at 10-metre precision is inventing accuracy the input never had.
2) Density that spans four orders of magnitude
- Query 5 km, ship it.
- Manhattan returns tens of thousands of candidates you immediately throw away, and the deck build blows its latency budget sorting people nobody will see.
- Montana returns two, then one, then none. The product is empty and the user leaves.
- The same query is simultaneously too expensive and useless, which is a good sign the parameter is the wrong one.
- Expose a distance slider and honour it. Necessary as a product feature, and it does help the rural case.
- But it makes the user solve an engineering problem: nobody knows whether to ask for 50 km or 200 km, and they will drag it around until something appears.
- It also does not bound the work: a rural user dragging to 500 km issues exactly the enormous query you were trying to avoid.
- The query asks for about three hundred candidates, and the radius is whatever it takes to find them. Start at a level sized for local density, and step out one level at a time until the count is met.
- Each step out to the next coarser cell level covers roughly four times the area, so it converges in a handful of lookups even from a very sparse start. Manhattan is satisfied at the first level with roughly 380 candidates in a single square kilometre; Montana needs about 12,000 square kilometres for the same 300, which is six or seven steps and a radius near 60 km.
- The 380 comes from the implied dater rate of about 1.4 percent. Rural Montana holds about 0.025 candidates per square kilometre.
- Six or seven lookups is still cheap. The point is that the SAME loop serves both, not that both finish quickly.
- Store an estimated density per cell so the build starts at the right level rather than discovering it. The estimate comes from the index itself. That turns the common case into a single lookup instead of a walk.
- The user's slider becomes a filter, not the query. They cap how far they will travel; the system decides how far it must look to fill a deck.
- Cap the expansion, and past the cap show "nobody nearby" rather than a distant match. "There is nobody nearby right now" is a better answer than someone three states away presented as local, and it is also what stops one lonely user issuing a continental query.
- Hot shards are the consequence and they need naming: a dense city's cells are read constantly, so those shards get read replicas. It is a read-only, cacheable, small dataset, which is the easiest kind of hotspot to fix.
3) Moving users, and how little you need to know
- Subscribe to location updates and post each one.
- 10M devices at one hertz is 10M writes a second, which is four thousand times the traffic the product actually needs.
- It is also the fastest way to get uninstalled: continuous GPS is one of the few things a user can feel in their battery.
- Send a fix every five minutes while the app is open. Much better, and it is where most designs land.
- It still writes constantly for the large majority of users who have not moved at all.
- And it stops entirely when the app is backgrounded, which is exactly when someone commutes across town.
- Fifteen minutes of location lag is invisible to the product, and that staleness budget is what buys a lossy, unordered, cheap write path.
- Use the OS significant-change API, which wakes the app only when the user has genuinely moved, a few hundred metres. It uses cell towers and wifi rather than GPS, at a tiny fraction of the power.
- The goal on this path is to make the write count smaller, not to serve a large count faster.
- Only write when the CELL changes, which the client can decide for itself. Moving within a cell changes nothing in the index, so the write is pure waste.
- Age out users who stop appearing. Someone dormant for thirty days is removed from the index, which keeps the ghost problem from quietly widening everyone's radius. A stale index is worse than a small one.
- Accept a sudden 3,000 km jump, but flag it to the safety systems, because the user may be spoofing rather than on a plane.
4) Trilateration, and why jitter is not the answer
- "1.2 km away" is friendly and precise.
- Spoof your GPS to position A and read the distance. Move to B, read again. Then C. Three circles intersect at one point, and that point is a home address.
- This is not hypothetical: it has been demonstrated against real dating apps more than once, and the fix each time was to stop returning precision.
- Returning coordinates directly is the same bug with fewer steps, and it has shipped too, usually in an API response the client never displayed.
- Round to the nearest kilometre, or add a small random offset. Both feel like they should work.
- Rounding alone still leaks: sample from many positions and the boundaries where the rounded value flips trace out the true circle.
- Random noise is worse, because it is defeated by repetition. Query fifty times, take the mean, and the noise cancels while the signal stays.
- The flaw in both is the same: the attacker controls the number of samples, so anything that varies per query averages out.
- Snap both users' stored coordinates to their grid cell centres and compute the distance from those centres. The output is now a property of the cell pair, not of the true positions.
- Determinism is the whole point: the same pair always produces the same answer, so repeated sampling reveals nothing new. Averaging has nothing to average.
- Report a distance bucket such as "under 2 km", not a number, and widen the buckets with distance. Close up, one-kilometre steps; far away, ten-kilometre steps, because far-away precision has no product value and identical privacy cost.
- Make the distance field a string in the API type, so no client, analytics event or debug endpoint can leak a float later. That makes it structural rather than a rule people remember. Strip EXIF from photos for the same reason.
- Do not sort the deck by true distance, because the ORDER re-encodes the precision you just removed. Sort within a bucket by something else.
- Say what it costs. The product is slightly worse, the safety property is worth it, and there is a floor below which you should simply refuse to be precise regardless of what the design team wants.
5) The deck, and why swiping is free
- Fetch the next candidate when the user swipes.
- 11,500 swipes a second becomes 11,500 spatial queries a second, ten times the deck rate, for a result that has not changed since the last one.
- It also puts a network round trip in the animation, which is the one place in this product where latency is actually felt.
- Fetch twenty at a time and refill in the background. Right instinct, and it fixes the animation.
- The refill still lands mid-session, so a heavy swiper generates a steady stream of spatial queries anyway.
- And paging over a set that is changing underneath you repeats and skips people unless the cursor is stable.
- Build about a hundred candidates when the app opens and cache the list with a 30 minute TTL. Every swipe reads from it, so the swipe path has no spatial work in it at all.
- 11,500 swipes a second collapse onto 1,200 deck builds a second, which is why the rate asymmetry matters: the expensive thing now happens an order of magnitude less often than the cheap thing.
- The exclusion set of users already seen is the part that is genuinely hard, and a compressed bitmap is the structure for it.
- It only grows, it is consulted on every build, and a heavy user has tens of thousands of entries.
- A compressed bitmap of user ids keeps it to kilobytes and turns the check into a fast intersection rather than tens of thousands of lookups.
- A Bloom filter is the tempting alternative and is the wrong trade here: a false positive silently hides a real person forever, and the user can never discover it.
- Rebuild when the deck runs low, the TTL expires, the user changes their filters, or they move to a new cell. Those are the triggers that actually matter. Not on a timer.
- Accept that the deck is a snapshot. Someone may go offline, change their preferences or swipe you first while they sit in your cached deck. None of that is a correctness problem, and pretending it is leads to a much more expensive design for no product gain.
Three more dives, briefly
- Travel mode, where the user sets a location explicitly, breaks the assumption that location follows the device.
- An explicitly set location is just another cell write, so the index does not care. What changes is that
lastSeenAtand the cell no longer agree with the device, so any safety heuristic built on "did they teleport" has to know the difference. - It also has to expire, or a user is discoverable in a city they left months ago.
- The interesting consequence: a user can be in two markets' decks in one day, which matters for anything that reasons about a local population.
- An explicitly set location is just another cell write, so the index does not care. What changes is that
- Naive geo breaks at borders, oceans and the antimeridian, where longitude wraps at 180 degrees.
- A user in a border city has half their candidate population in another country, another language and another legal regime. The index does not care and the product very much does.
- Longitude wraps at 180 degrees, so a circle spanning it becomes two ranges. Cell-based indexes handle this natively, which is one more reason not to hand-roll bounding boxes.
- Distance on a sphere is not distance on a plane. At dating distances the error is small, but the poles and the wrap are where the flat approximation stops being harmless.
- Live location would remove the staleness budget, and with it most of what makes this design cheap. It is the question that reframes everything.
- A "who is here right now" feature removes the staleness budget, and with it the lossy write path, the cached deck and most of the reason this design is cheap.
- That is the honest answer to why this looks nothing like a ride-hailing system: not because the geometry is different, but because the freshness requirement is.
- It also raises the safety stakes sharply, since real-time presence is a much more dangerous signal than an approximate distance.
- With a naive prefix match, nothing: they share no cell prefix, so neither ever appears in the other's deck.
- This is the single most common defect in this design, and it is invisible in testing because test users are never 40 metres apart across a line.
- The fix is to always query the eight neighbouring cells as well as the centre one, so the covering set is a superset of the circle.
- Then filter exactly with haversine on the few hundred candidates, which is microseconds, so the index only ever has to be a good superset.
- Hexagonal cells reduce the corner cases because all six neighbours are equidistant, which is a real reason to prefer H3 over a square grid.
- Density spans four orders of magnitude: about 28,000 people per square kilometre against about 1.8.
- A 5 km circle is 78 square kilometres either way, so it holds about 2.2M people in one and about 140 in the other.
- So a fixed radius returns tens of thousands of candidates you throw away, or an empty product. Both are failures of the same parameter.
- Query for a target count of a few hundred instead, and step out one cell level at a time until it is met. Each level is roughly 4x the area.
- Manhattan is done at the first level, about 380 candidates in a square kilometre. Montana needs roughly 12,000 square kilometres for 300, so six or seven levels and a radius near 60 km. Same loop, very different answer.
- Store an estimated density per cell so the common case starts at the right level rather than walking to it.
- Cap the expansion, and past the cap say "nobody nearby" rather than presenting someone three states away as local.
- Spoof your own position three times, read the distance each time, and intersect the three circles. They meet at one point.
- Three queries is all it takes, and it has been demonstrated against real dating apps more than once.
- Rounding alone still leaks, because sampling many positions traces out the boundary where the rounded value flips.
- Random jitter is worse: the attacker controls the sample count, so averaging fifty queries cancels the noise and leaves the signal.
- The fix is deterministic quantization BEFORE measuring: snap both users to a cell centre, compute from there, so the same pair always returns the same answer and repetition reveals nothing.
- Report a bucket as a string, widen buckets with distance, never return lat/lon from any endpoint, and do not sort the deck by true distance, because the ordering re-encodes what you just removed.
- Only on significant change, and only when the cell actually changes. Moving within a cell changes nothing in the index, so that write is pure waste.
- Get it wrong in the expensive direction and a 1 Hz GPS loop on 10M devices is 10M writes a second and a battery the user can feel draining. They uninstall before the index notices.
- Get it wrong in the cheap direction and only-on-foreground misses the commute across town, which is exactly the movement that matters.
- The budget being spent is staleness: fifteen minutes of lag is invisible to a dating product, and that is what makes the write path lossy, unordered and cheap.
- Age out anyone dormant for thirty days, or ghosts quietly widen everyone's radius while never replying.
- Zero. The deck of about a hundred candidates was built when the app opened and cached with a TTL.
- That is the whole reason the rates are shaped the way they are: 11,500 swipes a second collapse onto about 1,200 deck builds a second.
- Querying per swipe would put a network round trip inside the animation, which is the one place in this product where latency is actually felt.
- The deck rebuilds on real triggers: running low, TTL expiry, a filter change, or moving far enough to change cells. Never on a timer.
- The genuinely hard part is the exclusion set of already-seen users: it only grows, so use a compressed bitmap, and not a Bloom filter, because a false positive hides a real person forever and nobody can discover it.
- The deck is a snapshot and that is fine: someone going offline or changing filters mid-deck is not a correctness problem.
Final design + what is expected at each level
wrapFinal Design
- The client sends a fix only when the OS reports real movement, and only when that movement crosses a cell, so the write count is small by construction rather than by throttling.
- The location service answers 204, moves the user between cells, stamps
lastSeenAt, and keeps no coordinate history. - The index is cell id to a set of user ids, under a gigabyte for 10M users, sharded by cell prefix with read replicas on the dense shards.
- A deck build covers the circle with cells including the eight neighbours, steps out a level when the count is short, filters exactly by haversine, removes the already-seen bitmap, and caches about a hundred candidates.
- Swipes read the cached deck, so the highest-rate operation in the product does no spatial work at all.
- Every distance is computed from grid-snapped positions and returned as a bucketed string, and no endpoint returns another user's coordinates.
- The invariant worth closing on: a location fifteen minutes old is good enough, and that single tolerance is what pays for the cheap write path, the cached deck and the coarse index. The two things it does not pay for are density and safety, which are the two dives worth having.
What is Expected at Each Level
- Mid:
- Reaches a geohash or Redis GEO index and a query by radius, which is a working answer.
- Separates the location write from the candidate read.
- Usually misses the neighbour-cell boundary bug entirely.
- Usually treats distance as a display detail rather than a safety property.
- Senior:
- Handles the boundary correctly and filters exactly after over-fetching.
- Notices the density problem and adapts the radius or the cell level to it.
- Caches the deck so the swipe path does no spatial work, and can say why that ratio matters.
- Throttles location updates deliberately and can defend the interval.
- Rounds the distance rather than returning it exactly, though may not see that rounding and random noise both still leak to repeated queries.
- Staff:
- Leads with the staleness tolerance and uses it as the reason for at least three separate decisions rather than mentioning it once.
- Reframes the query from a radius to a target count, and knows the cell level is the lever rather than the circle.
- Raises trilateration unprompted, and knows why jitter fails where deterministic quantization works.
- Catches the second-order leak: sorting the deck by true distance re-encodes the precision that bucketing removed.
- Picks the exclusion-set structure on the right grounds, rejecting a Bloom filter because a false positive is invisible and permanent.
- Names what the design does not do: the deck is a stale snapshot, ghosts need ageing out, and a live-presence feature would invalidate most of the cheapness.
Say the opening tolerance out loud without notes: fifteen minutes stale is fine, so the write path is lossy, unordered and cheap.
Then draw the boundary bug from memory: two dots forty metres apart, a cell line between them, and the eight neighbours you have to query.
Then state the trilateration fix in one sentence: snap both users to a cell centre before measuring, deterministically, because jitter averages away.