Proximity / Nearby Service — Detailed

flowchart TB
  subgraph Clients
    APP[App]
  end

  subgraph Edge
    CDN
    GW
  end

  subgraph Query[Query API]
    NEAR[Nearby k-NN]
    RAD[Radius search]
    BBOX[Bounding box]
    AUTO[Autocomplete with location bias]
  end

  subgraph Indexes[Spatial Indexes]
    QT[Quadtree]
    GH[Geohash prefix tree]
    S2[S2 cells]
    H3[H3 hexagons]
    RTREE[R-tree for polygons]
  end

  subgraph Data
    PSVC[Place Service]
    PDB[(Places sharded by cell)]
    CACHE[(Hot cell cache)]
  end

  subgraph Ingest
    UP([POI ingest pipeline])
    GEOC[Geocoder]
    DEDUP[Dedup / merge]
  end

  subgraph Ranking
    REL[Relevance + distance combine]
    PER[Personalization]
  end

  Clients --> CDN --> GW --> Query
  Query --> Indexes --> PDB
  Query --> CACHE
  PDB -. seed .-> Indexes
  Ingest --> PSVC --> PDB
  Ranking --- Query

    classDef client fill:#dbeafe,stroke:#1e40af,stroke-width:1px,color:#0f172a;
    classDef edge fill:#cffafe,stroke:#0e7490,stroke-width:1px,color:#0f172a;
    classDef service fill:#fef3c7,stroke:#92400e,stroke-width:1px,color:#0f172a;
    classDef datastore fill:#fee2e2,stroke:#991b1b,stroke-width:1px,color:#0f172a;
    classDef cache fill:#fed7aa,stroke:#9a3412,stroke-width:1px,color:#0f172a;
    classDef queue fill:#ede9fe,stroke:#5b21b6,stroke-width:1px,color:#0f172a;
    classDef compute fill:#d1fae5,stroke:#065f46,stroke-width:1px,color:#0f172a;
    classDef storage fill:#e5e7eb,stroke:#374151,stroke-width:1px,color:#0f172a;
    classDef external fill:#fce7f3,stroke:#9d174d,stroke-width:1px,color:#0f172a;
    classDef obs fill:#f3e8ff,stroke:#6b21a8,stroke-width:1px,color:#0f172a;
    class APP,NEAR,RAD,BBOX,AUTO,QT,GH,S2,H3,RTREE,PSVC,GEOC,DEDUP,REL,PER service;
    class PDB,CACHE datastore;
    class UP compute;

Index choices

Index	Strengths	Weaknesses
Quadtree	adaptive density	unbalanced trees
Geohash	string-prefixable, easy sharding	corner cases at edges
S2	sphere-aware, uniform cells	learning curve
H3	hexes have nice neighbor properties	non-hierarchical
R-tree	shapes, not just points	harder to shard

k-NN approach

• Locate cell containing query point.
• Iteratively expand to neighbor cells until enough candidates.
• Sort by Haversine distance; return top-k.

Glossary & fundamentals

Concepts referenced in this design. Each row links to its canonical page; the tag column shows whether it is a high-level (HLD) or low-level (LLD) concept.

Tag	Concept	What it is	Page
HLD	CDN	edge caching for static assets	cdn
HLD	Sharding	horizontal partitioning across nodes	database-sharding
HLD	Geo indexing	Geohash, Quadtree, S2, H3, R-tree	geo-indexing