GeoLock.Site

The web can gate by almost anything — except place

Content on the web can be gated by identity, by payment, by time, by invitation. Almost never by place. GeoLock makes physical presence the key: a drop is pinned to a point on the map with an unlock radius, and its content reveals itself only to people who are physically inside that zone, browsing what's nearby. There is no link to send — presence itself is the access mechanism.

That constraint is the point, not an omission. The use cases are practical, not playful: a county emergency service posting a wildfire warning that only residents and travelers currently in the affected area will ever see; a festival or fair broadcasting schedule changes to the people actually on the grounds; a traveler leaving a message findable only by someone standing at a specific meeting point, useful precisely when a phone is lost or a network is unreliable overseas. In each case, remote visibility would be a liability — the information is only relevant, or only safe, where it's tied to place.

What makes it interesting as a systems exercise is where the gate lives: not in application code comparing distances, but in the database, as a spatial predicate. Discovery is a SQL query that either returns nearby drops or doesn't.

The build ran as fifteen implementation tickets executed strictly in sequence — a deliberate constraint to practice working from a fixed backlog rather than improvising scope mid-flight.

What it must do — and under what conditions

FR	Create a drop: pick a point on the map, set an unlock radius, choose an expiration, give it a title (its displayed identifier), optionally set a drop key as a password, attach content. Discover drops: no links exist anywhere — a user is shown only the drops currently near their reported position, browsed by title. Opening a titled drop from that nearby list returns content only if the position check passes and, if a key is set, the correct key is supplied. Search for places by name when placing a drop; a create flow that works on a phone.
NFR	The unlock decision is server-side — the client never receives content before the check passes. Drops outside a user's current area must be unreachable and non-enumerable, not merely hidden by the UI. The mapping stack must be free of API keys and billing. The whole flow must work outdoors on a phone, where GPS accuracy is a real variable, not a lab constant.
Constraints	One shared VPS hosting other Softwarean projects; PostGIS runs in Docker; nginx in front of the API.

The gate lives in the database

A React + Leaflet SPA served by nginx; a Fastify API behind the same nginx; PostGIS in a Docker container as the single store — and the single decision-maker. The browser talks to two external services directly: CartoDB Voyager for map tiles and Nominatim for place search. Neither ever sees drop content; they only serve the map. The API receives the reported position and delegates the inside-or-outside question to PostGIS.

Four decisions that shaped the system

Digests of the ADRs that mattered. Each one names what the decision cost — a trade-off you don't acknowledge is a trade-off you didn't see.

Discovery and unlock are the same predicate, asked twice

A drop is a row: a title (its display identifier — currently unenforced for uniqueness, more on that below), an optional hashed key, an expiration timestamp, content, a point on the earth stored as geography(Point, 4326), and an unlock radius in meters. There is no slug and no link column — nothing in the schema is designed to be addressed remotely. The same spatial predicate answers two different-sounding questions: "what's near me?" (discovery, no title known yet) and "may I read this one?" (unlock, title already chosen from the list):

-- discovery: what's near me right now?
SELECT title
FROM   drops
WHERE  (expires_at IS NULL OR expires_at > now())
AND    ST_Within(
         ST_SetSRID(ST_MakePoint($1, $2), 4326)::geometry,  -- $1 = lng, $2 = lat. In that order.
         unlock_zone::geometry
       );

-- unlock: open the one I picked
SELECT content
FROM   drops
WHERE  title = $3
AND    (key_hash IS NULL OR key_hash = crypt($4, key_hash))
AND    (expires_at IS NULL OR expires_at > now())
AND    ST_Within(
         ST_SetSRID(ST_MakePoint($1, $2), 4326)::geometry,
         unlock_zone::geometry
       );

Two properties of this design carry the system. First, geography means distances and containment are computed in meters on a spheroid — no hand-rolled projection math, no degrees-to-meters conversion to get wrong. Second, because the gate is a database predicate, it is testable in isolation: feed psql a coordinate known to be inside a zone and one known to be outside, and the security model of the whole product is verified in two queries — the same two queries run for real discovery.

The comment on the point constructor is not decoration. PostGIS point constructors take (x, y) — longitude first — while every human-facing convention, from Leaflet to spoken coordinates, is latitude first. That single inversion produced the project's defining bug, covered below.

The unenforced uniqueness on title is a deliberate deferral, not an oversight: multiple unrelated drops can currently share a display name, since nothing yet needs a global namespace. The planned next step — a freemium tier where paid accounts can reserve a unique title — turns that open question into the product's first monetization lever rather than a bug to fix defensively now.

The bug that never errors

ST_MakePoint(lng, lat) — and I called it with (lat, lng). Nothing fails. The arguments are both valid floats, the point is a perfectly legal location — just the wrong one, coordinates transposed across the globe. Every unlock attempt returned "not there yet" while standing on the exact spot. No exception, no log line, no hint: the system was working flawlessly on a question nobody meant to ask. Diagnosis came from casting the stored point back to text in psql and reading the raw coordinates — at which point the transposition was obvious in one glance. The class of bug is worth naming: an interface where argument order is the only contract, both arguments share a type, and the failure mode is silent semantic corruption. Type systems don't catch it; only a test with a known real-world coordinate does.

The phantom failure

A success path that reported failure: the frontend's fetch wrapper called .json() on every response, and endpoints returning 204 No Content — which have, by definition, no body — made the wrapper throw Unexpected end of JSON input. The operation had succeeded on the server; the UI showed an error anyway. The fix is trivial (branch on status before parsing), but the lesson generalizes: a response wrapper is an interface contract with every endpoint, including the bodyless ones you haven't written yet.

The gate was tested from both sides

• The predicate verified directly in psql: a coordinate known to lie inside a test drop's zone returns the content; a coordinate meters outside returns zero rows. Same query, both sides of the fence.
• The full path verified in the field: a drop created on desktop, then unlocked from a phone standing at the pinned location — reported GPS position, real network, real accuracy noise.
• The server-side-gate NFR checked at the API boundary: a locked drop's read endpoint returns no content payload for an outside position — the content isn't hidden by the UI, it never arrives.
• The optional key checked both ways: a keyed drop returned content from inside the zone with the correct key, and was refused with the wrong key even though the position check passed.
• Expiration checked by advancing a test drop's expires_at into the past: it stopped appearing in the discovery query and its unlock query returned zero rows, with no separate code path needed for either.

If I rebuilt it

• A minimum unlock-radius floor, derived from typical phone GPS accuracy. A 10-meter zone plus 25 meters of GPS noise means standing inside and reading "outside" — the current design lets creators configure a frustration machine.
• Show the accuracy circle on the map during an unlock attempt. When the gate says no, the user should see why: their reported position and its uncertainty, next to the zone.
• One integration test with a known real-world coordinate, written on day one. It would have caught the coordinate-order bug before it cost an afternoon — the cheapest test in the whole project would have paid for the most expensive bug.
• Rate limiting on the discovery and unlock endpoints. A spoofable position means an attacker can probe for nearby drops from an armchair; a per-IP limit makes the lazy version of that attack boring.
• Next step, not a regret: a freemium tier where paid accounts can reserve a unique title. Titles are unenforced for uniqueness today by choice — turning that into a feature rather than patching it defensively is the plan, not a gap that slipped through.