Design the geolocation half of Tinder or Bumble

Functional Requirements

1. A user's location should follow them as they move, without draining the battery.
2. A user should get a deck of nearby candidates that respects their distance preference.
3. The distance shown should be useful to a dater and useless to a stalker.
4. 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.
• Travel mode stays in scope as a constraint, because a user who sets their location to another city breaks the assumption that location follows the device, and the design has to survive it.

Non-Functional Requirements

• Say the staleness tolerance first, because it is the affordance the whole design spends.
  • A location fifteen minutes old is fine. 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".
• Then the three rates, because they are not close to each other.
  • Location writes: about 2,300 a second. Small, and the goal is to make it smaller rather than to serve it faster.
  • Deck builds: about 1,200 a second. This is the only expensive read in the system.
  • Swipes: about 11,500 a second, and they must cost ZERO geo work, because the deck was already built.
  • 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.
• Density is the requirement people forget, and it is the one that breaks naive designs.
  • Manhattan is about 28,000 people per square kilometre. Rural Montana is about 2.7. That is four orders of magnitude.
  • A 5 km circle covers 78 square kilometres either way: about 2.2M people in one and about 200 in the other.
  • One fixed radius therefore returns a crowd you throw away, or an empty product. Both are failures.
• 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.
• Safety is a functional requirement wearing a non-functional hat. Precise distance is a coordinate in disguise, 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.

Defining the Core Entities

• User is the profile plus the preferences that bound every query: maxDistanceKm, age range, and discoverable. 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 deliberately not a stored history: userId, cellId, lastSeenAt. The raw fix is used to compute the cell and then thrown away.
  • 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: cellId to 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 a materialised list: userId to an ordered list of candidate ids with a TTL. It exists so the swipe path never queries anything spatial.
• 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, and that is a design statement. Nothing reads its own write, 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.24 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 can use them to precompute rather than being handed them at read time.

1) Location follows the user, cheaply

• The client decides when to send, and that is where the win is.
  • Both platforms expose a significant-change API that wakes the app when the user has actually moved a few hundred metres, rather than on a timer.
  • A one-hertz GPS loop on 10M devices is 10M writes a second and a flat battery by lunchtime. The product would die long before the index did.
  • So the design goal on this path is to make the write COUNT smaller, not to serve a large count faster.
• 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 raw coordinate is used to compute a cell and is not kept.
• Age out dormant users, or the index quietly rots. Someone who has not opened the app in a month is a ghost in the deck: they widen everyone's radius while never replying. A stale index is worse than a small one.

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 circle is not a cell, so the query over-fetches on purpose.
  • Cover the query circle with the cells that overlap it, read everyone in those cells, then measure exact distance and drop the corners the circle never reached.
  • Over-fetching is cheap and filtering is exact. Trying to make the index answer the circle precisely is the wrong instinct.
• The boundary bug is the one everybody ships once, so say it before you are asked. Two people forty metres apart can sit either side of a cell line, share no prefix, and never see each other. You must query the eight neighbouring cells, always.
• Cell size is the tuning knob and it has one tradeoff: coarser cells mean more over-fetch and fewer lookups; finer cells mean less waste and more neighbours to read. Pick per density rather than globally, which is section 3.
• 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.

3) Building a deck that works at both extremes

• Query for a target COUNT, not for a distance. The user wants a deck; the radius is the means. Aim for a few hundred candidates and let the radius be whatever produces them.
• Expand by cell level, not by re-running a circle. Each level out is roughly four times the area, so a handful of lookups covers an enormous range of densities.
  • Do the arithmetic rather than waving at it. At the implied dater rate of about 1.4 percent, one square kilometre of Manhattan holds around 380 candidates, so the first level already satisfies the target.
  • Rural Montana holds about 0.025 candidates per square kilometre, so 300 of them needs roughly 12,000 square kilometres, which is a radius near 60 km and six or seven levels out.
  • Six or seven lookups is still cheap. The point is that the SAME loop serves both, not that both finish quickly.
• Cap the expansion and be honest about the result. Without a maximum a lonely user eventually queries a continent. Past the cap the correct product answer is "there is nobody here", not a match three states away presented as if it were local.
• Exclude everyone already swiped, and treat that set as a real problem. It only grows, it is checked on every build, and a heavy user has tens of thousands of entries. A compressed bitmap keeps it to kilobytes and makes the check a cheap intersection.
• Cache the deck, because that is what makes the swipe path free. Build about a hundred candidates on app open, serve swipes from it, and rebuild when it runs low or the TTL expires. 11,500 swipes a second then cost nothing spatial at all.

4) A distance that cannot be triangulated

• State the attack plainly, because it is documented and it has happened to real apps. Spoof your own position three times, read the reported distance each time, and intersect the three circles. Three queries turn a distance into an address.
• Precision is the vulnerability, not the distance itself. A dater needs to know roughly how far; they never need two decimal places.
• Snap to a grid BEFORE computing, and do it deterministically.
  • Both users are moved to their cell centre and the distance is computed from there, so the same pair always yields the same answer.
  • Random jitter does not work and it is worth saying why: query fifty times and average the noise away. Only deterministic quantization survives repetition.
• Widen the buckets with distance. A kilometre of precision matters at two kilometres and is meaningless at fifty, while costing the same privacy either way.
• The product cost is real and you should own it: "under 2 km" is a worse experience than "1.2 km". It is still the right trade, and being able to say why is the point of the dive.

1) What actually answers "who is near me"?

2) Density that spans four orders of magnitude

3) Moving users, and how little you need to know

4) Trilateration, and why jitter is not the answer

5) The deck, and why swiping is free

Three more dives, briefly

• Travel mode, which 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 lastSeenAt and 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.
• Borders, oceans and the antimeridian, which is where naive geo breaks.
  • 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.
• What changes if the product needs live location, which 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.

Final 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.
• 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.