Map & radar

The map is the discover view's spatial surface. The radar is the proximity-first complement — a list of people nearby, sorted by distance. Both share data but answer different user questions: the map shows what is happening where, the radar shows who is near me right now.

Entry points

From	Action
Sign-in	Default landing — /discover opens with the map.
Nav dock	Compass icon → /discover.
Map dock → Radar pill	Opens the Radar sheet on top of the map.
Map dock → Legend pill	Opens the marker legend.
Map dock → Active Location pill	Opens the presence sheet.
Long-press on map	Drops a pin; an action menu offers "Create event here" / "Drop a moment".

Primary flow — map

1. Open the map. Centered at the user's current location (or San Francisco fallback). Markers fade in over the first few hundred milliseconds.
2. Pan and zoom. Standard touch gestures. As the viewport changes, markers refetch in the background. At low zoom, markers collapse into clusters; at high zoom, individual pins appear.
3. Tap a marker. Opens the detail sheet. Marker type determines the sheet:
   • Event marker → event detail.
   • Location marker → place card with photos, top moments, upcoming events at that place.
   • Standalone moment marker → moment detail.
   • Friend marker → profile-mini.
   • Cluster marker → carousel of contents + center-and-zoom action.
4. Inspect, then dismiss. Swipe the sheet down to close; the map remains panned where the user left it.
5. Use the dock. A horizontal dock above the bottom nav offers Radar, Active Location, and Legend.

Primary flow — radar

1. Open Radar. Tap the Radar pill from the map dock. A bottom sheet rises.
2. See the list. Two sections: Friends nearby (sorted by distance) and Near You (strangers within radius, sorted by distance). Each row: avatar, name, distance, last-active indicator.
3. Adjust radius. A slider at the top sets the radius (in km). The list updates as the slider moves.
4. Tap a friend. Opens profile-mini with "Open profile" and "Message".
5. Tap a stranger. Opens their public profile. From there: "Add friend" or "Message" (if DMs to strangers are allowed by their preferences).
6. Dismiss. Swipe down to close. The radar's last radius is preserved on the user's device.

Sub-flows

Sub-flow	Behavior
Geo-cluster tap (low zoom)	First tap centers the map on the cluster and shows a carousel preview at the bottom. Second tap (or a carousel tap) zooms in one tier.
Supercluster tap (mid zoom)	Cluster expands to its children with a soft animation — no center / preview phase.
Friend marker overlay	Friend markers always render as individual pins, regardless of zoom — they never roll into a cluster.
Sponsored events at low zoom	Global-tier sponsored events render as priority markers; the user sees them even at continent zoom. Hyper-local sponsored events are filtered at low zoom to avoid clutter.
User's own events	Events the user is hosting or has joined are flagged as priority markers — they always show through clustering.
Map theme	The map's tile style follows the user's theme preference (light / dark / system). The dark theme uses a darker tile set; the light theme uses standard.
Long-press → create	Long-press on an empty area drops a pin. An action menu offers "Create event" (opens the create modal with coords prefilled) or "Drop a moment".
Search a place	A search input at the top of the map searches places by name. Tapping a result moves the camera to that place.
Recenter	A "Find me" button on the map snaps the camera back to the user's location. Requires location permission.
Radar empty	When no friends or strangers are within radius, the radar shows: "No one's nearby. Try widening the radius."
Radar offline / errored	A red toast appears; the radar shows the last cached result if any.

States

State	What the user sees
Map loading first markers	A thin progress bar at the top; markers fade in.
Map idle (no pan / zoom)	Markers are stable; the dock is visible; the user's own marker is centered.
Map panning fast	Marker fetches debounce. Existing markers stay rendered until the new payload arrives, then swap.
Cluster selected (low zoom)	Cluster gets a highlight ring; carousel slides up at the bottom showing the cluster's contents.
Sheet open	Map dims slightly; the sheet covers the lower portion.
Location permission denied	A banner offers "Enable location" → opens system settings. The map opens at default region; "Find me" is greyed out.
Offline	Map tiles continue to render from cache if previously loaded; markers go stale (dimmed). A red banner: "Offline."
Friend live marker	Pulses gently to indicate active sharing. Tap → profile-mini with countdown to expiry.

Marker types — reference

Marker	Looks like	Tap behavior
Event	Calendar icon, category-tinted	Event detail sheet
Location	Map pin with category icon	Place detail sheet
Standalone moment	Camera badge over coords	Moment detail sheet
Friend (live)	Pulsing avatar pin	Profile-mini with live indicator
Friend (static)	Static avatar pin	Profile-mini
Geo-cluster (low zoom)	Counts pill ("23 events, 7 places")	Center + carousel; second tap zooms
Supercluster (mid zoom)	Numeric count	Expand to children
User (self)	Distinct color avatar, optional pulse	No detail; "Find me" recenter

Edge cases & gotchas

• Marker caps at low zoom. The backend caps how many individual markers are returned at city / neighborhood zoom (200 / 200 / 100 for events / locations / moments at city, scaling up at higher zoom). The user does not see this cap explicitly — there is no "showing 100 of 437" UI; the cap is just enforced.
• Friend markers ignore caps. Friends always render as individual markers, regardless of marker caps or zoom.
• Sponsor filter at low zoom. At city zoom and below, events with hyper-local sponsorship are filtered out so the global view isn't drowned. This is invisible to the user.
• Cluster carousel is read-only on first tap. The first tap is a preview affordance, not a navigation action. Tapping a card in the carousel zooms.
• Radar radius is in km client-side but converted to metres for the backend. The user always sees km on the slider.
• Stale presence on radar. A stranger or friend whose presence TTL has expired (>3 min) drops off the radar even if they're "nearby" by last-known location. This is by design — radar means "right now".
• Profile-mini is the lean card. A friend-marker or radar tap opens the lean identity card (name, avatar, bio, friend status). "Open profile" is a separate, heavier read that aggregates moments, events, and mutuals. See Profile & settings.
• Profile-mini sheet stacks. Opening a friend marker, then opening another from the radar, stacks sheets. Back closes the topmost; the previous is restored intact.
• Backgrounding mid-pan. The viewport state is preserved; on resume, one fresh fetch is issued.
• Search miss. A place search that returns no result shows an inline "No places match" hint; the map does not jump.

See also

• product/bible/ — narrative for the map (TBD).
• product/domains/ — viewport caps, sponsor priority, friend overlay (TBD).
• Discovery feed — the list-view complement to the map.
• Presence & live location — what makes a friend marker live.
• Events — what an event marker tap leads to.
• Moments — what a moment marker tap leads to.
• Frontend → Routing — /discover route hosting the map.
• Backend → Discovery service — viewport tier strategy, marker caps, friend overlay.