Design Foursquare (Check-ins and Recommendations)

Check-In Validation and Discovery Flow

The system evaluates client location coordinates against venue coordinates, confirms physical proximity to prevent fraud, and executes high-throughput spatial queries across millions of registered venues.

Venue Discovery: Nearby Search

Approach 1: PostGIS spatial query
  Accurate, supports complex filters. DB query per request → may not handle 10K QPS.

Approach 2: Elasticsearch geo query ⭐
  Full-text + geo + filtering in one query. Handles 10K+ QPS.

Recommended: Elasticsearch for user-facing search; PostGIS for admin queries

Check-in Flow and Kafka Event Pipeline

Topic: checkin-events
  Partitions: 32
  Partition key: user_id (keeps a user's check-ins ordered for idempotency)
  Retention: 7 days
  Replication factor: 3, min.insync.replicas: 2

Producer: Check-in Service after PostgreSQL INSERT (sync path returns 201 first)
  Event: { event_id, checkin_id, user_id, venue_id, lat, lng, shout, visibility, timestamp }

Consumer groups:
  1. feed-writer: LPUSH friend_feed:{friend_id} for visible check-ins
  2. mayorship: ZINCRBY mayor:{venue_id} (atomic, tie-break by timestamp)
  3. venue-stats: INCR venue checkin_count in Redis
  4. trending: ZINCRBY trending:{city} (1-hour sliding window)
  5. recommendations: update user preference vector
  6. notifications: push "Alice checked in at Tartine"

Sync path: validate → anti-fraud → Postgres INSERT → 201 (< 200ms)
Async path: gamification, feeds, and trending via idempotent consumers
DLQ: checkin-events-dlq; alert when mayorship consumer lag > 5 min

Recommendation Service: Personalized Venue Discovery

Recommendation signals:
  1. User Profile Vector (cuisine, price, time preferences)
  2. Collaborative Filtering
  3. Context-Aware: time of day, day of week, weather
  4. Venue Quality: rating, check-in count, tip sentiment

ML Architecture:
  Offline: Spark computes user/venue embeddings (128-dim) nightly
  Online: candidates from ES geo query → score = dot_product x recency x distance x context
  Cache in Redis (TTL: 15 min). Latency budget: ~100 ms total.

Mayorship: Race Conditions and Tie-Breaking

"Mayor" = user with most check-ins at a venue in the last 60 days

Redis: mayor:{venue_id} → Sorted Set { user_id: checkin_count_60d }

On check-in (async consumer):
  ZINCRBY mayor:{venue_id} 1 {user_id}
  current_mayor = ZREVRANGE mayor:{venue_id} 0 0
  if user_id == current_mayor → notify "You're the new mayor!"

Race: two users tie at same count → tie-break by earliest check-in timestamp
  (store score as count * 1e10 - timestamp for lexicographic ordering)

Daily cron: recompute from PostgreSQL for venues with disputed mayorships
  (handles Redis eviction or consumer lag > 24h)

Stale mayor window: if no check-in for 60 days, mayorship expires