docs(adr-0006): POI provider strategy — hybrid by category, phased

- Foursquare for café/restaurant (commercial), Geoapify/OSM for
  park/beach/viewpoint/museum (geography)
- CompositePoiProvider routes by category behind PoiProvider interface
- Phase 0 (now): Geoapify only, gap acknowledged
- Phase 1 (when Foursquare account ready): T-16
- Phase 3 (suggested-places panel): T-17 (depends on T-16)
- README + research note + TASKS.md updated

Author: TomerBenda

README.md

@@ -25,6 +25,8 @@ Open <http://localhost:3000>. See [docs/DEVELOPING.md](docs/DEVELOPING.md) for t
   - [ADR-0002 — Isochrone engine](docs/adr/0002-isochrone-engine.md)
   - [ADR-0003 — POI and tile providers](docs/adr/0003-poi-and-tile-providers.md)
   - [ADR-0004 — Deployment and AI workflow](docs/adr/0004-deployment-and-ai-workflow.md)
+  - [ADR-0005 — Navigation handoff](docs/adr/0005-navigation-handoff.md)
+  - [ADR-0006 — POI provider strategy (hybrid plan)](docs/adr/0006-poi-provider-strategy.md)
 
 ## Stack
 

apps/web/src/app/page.tsx

@@ -21,11 +21,12 @@ import {
 import { TimeSelector } from '@/components/controls/TimeSelector';
 import { ModeSelector } from '@/components/controls/ModeSelector';
 import { CategoryToggles } from '@/components/controls/CategoryToggles';
+import { SurpriseMe } from '@/components/controls/SurpriseMe';
 import { DestinationCard } from '@/components/destination/DestinationCard';
 import { tryGeolocate } from '@/lib/geolocation';
 import { useIsochrone } from '@/lib/hooks/useIsochrone';
 import { usePois } from '@/lib/hooks/usePois';
-import { bboxOf } from '@/lib/polygon';
+import { bboxOf, isInsidePolygon } from '@/lib/polygon';
 import { PUBLIC_CONFIG } from '@/lib/config';
 import {
   DEFAULT_CATEGORIES,
@@ -72,6 +73,12 @@ export default function HomePage() {
   const [state, setState] = useState<AppUrlState>(initialState);
   const [destination, setDestination] = useState<{ lng: number; lat: number } | null>(null);
   const [selectedPoi, setSelectedPoi] = useState<Poi | null>(null);
+  const [cameraTarget, setCameraTarget] = useState<{
+    lng: number;
+    lat: number;
+    zoom?: number;
+    key: number;
+  } | null>(null);
 
   // On mount: if no `lng`/`lat` in URL, ask for geolocation and use it.
   const askedGeoRef = useRef(false);
@@ -152,7 +159,37 @@ export default function HomePage() {
     bbox: polygonBbox,
     categories: state.categories,
   });
-  const pois = poiData?.pois ?? [];
+
+  // Polygon-clip the fetched POIs once and share the visible set with both
+  // PoiLayer (renders them) and SurpriseMe (picks from them).
+  const visiblePois = useMemo<Poi[]>(() => {
+    const list = poiData?.pois ?? [];
+    if (!data?.polygon) return list;
+    return list.filter((p) => isInsidePolygon([p.lngLat[0], p.lngLat[1]], data.polygon));
+  }, [poiData?.pois, data?.polygon]);
+
+  // If the selected POI falls out of the visible set (categories or time
+  // changed), dismiss it so the card doesn't orphan over an absent marker.
+  useEffect(() => {
+    if (!selectedPoi) return;
+    const stillVisible = visiblePois.some((p) => p.id === selectedPoi.id);
+    if (!stillVisible) setSelectedPoi(null);
+  }, [visiblePois, selectedPoi]);
+
+  const onSurprise = useCallback(() => {
+    if (visiblePois.length === 0) return;
+    const idx = Math.floor(Math.random() * visiblePois.length);
+    const pick = visiblePois[idx];
+    if (!pick) return;
+    setSelectedPoi(pick);
+    setDestination(null);
+    setCameraTarget({
+      lng: pick.lngLat[0],
+      lat: pick.lngLat[1],
+      zoom: 16,
+      key: Date.now(),
+    });
+  }, [visiblePois]);
 
   // Determine which destination (if any) gets the popup. POI selection wins
   // over a right-click drop point.
@@ -224,12 +261,12 @@ export default function HomePage() {
           }
           poiMarkers={
             <PoiLayer
-              pois={pois}
-              polygon={data?.polygon}
+              pois={visiblePois}
               onSelect={onPoiSelect}
               selectedId={selectedPoi?.id}
             />
           }
+          cameraTarget={cameraTarget ?? undefined}
         />
       </div>
 
@@ -248,7 +285,18 @@ export default function HomePage() {
             <ModeSelector value={state.mode} onChange={onModeChange} />
             <TimeSelector value={state.minutes} onChange={onMinutesChange} />
           </div>
-          <CategoryToggles value={state.categories} onChange={onCategoriesChange} />
+          <div className="flex flex-wrap items-center gap-2">
+            <CategoryToggles value={state.categories} onChange={onCategoriesChange} />
+            <SurpriseMe
+              disabled={visiblePois.length === 0}
+              onClick={onSurprise}
+              title={
+                visiblePois.length === 0
+                  ? 'No reachable POIs yet — toggle a category or expand time'
+                  : `Pick one of ${visiblePois.length} reachable places`
+              }
+            />
+          </div>
         </div>
       </header>
 

apps/web/src/components/controls/SurpriseMe.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import { Shuffle } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+interface Props {
+  disabled?: boolean;
+  onClick: () => void;
+  className?: string;
+  /** Tooltip override (useful for empty-state messaging). */
+  title?: string;
+}
+
+export function SurpriseMe({ disabled, onClick, className, title }: Props) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      title={title ?? (disabled ? 'Toggle categories or expand time to surprise yourself' : 'Pick a random reachable POI')}
+      aria-label="Surprise me"
+      className={cn(
+        'inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium shadow-sm transition-colors',
+        disabled
+          ? 'cursor-not-allowed border-border bg-background text-muted-foreground opacity-60'
+          : 'border-blue-600 bg-blue-600 text-white hover:bg-blue-700',
+        className,
+      )}
+    >
+      <Shuffle className="h-4 w-4" aria-hidden />
+      <span>Surprise me</span>
+    </button>
+  );
+}

apps/web/src/components/map/IlsochroneMap.tsx

@@ -9,7 +9,7 @@
  *     click events, and accepts a polygon and optional destination to render.
  *   - All provider logic stays out of components — they receive primitives.
  */
-import { useMemo } from 'react';
+import { useEffect, useMemo, useRef } from 'react';
 import Map, {
   Marker,
   Popup,
@@ -18,6 +18,7 @@ import Map, {
   NavigationControl,
   AttributionControl,
   type MapLayerMouseEvent,
+  type MapRef,
 } from 'react-map-gl/maplibre';
 import 'maplibre-gl/dist/maplibre-gl.css';
 import type { Polygon, MultiPolygon, Feature } from 'geojson';
@@ -45,6 +46,12 @@ interface Props {
   onMapBackgroundClick?: () => void;
   /** Optional POI markers to overlay. */
   poiMarkers?: React.ReactNode;
+  /**
+   * When this changes, the camera animates to the target. Used by "Surprise me".
+   * Include a `key` field that changes per invocation so repeated flights to
+   * the same lng/lat still fire.
+   */
+  cameraTarget?: { lng: number; lat: number; zoom?: number; key: number };
 }
 
 export function IlsochroneMap({
@@ -58,12 +65,35 @@ export function IlsochroneMap({
   onPickDestination,
   onMapBackgroundClick,
   poiMarkers,
+  cameraTarget,
 }: Props) {
   const polygonFeature = useMemo<Feature<Polygon | MultiPolygon> | null>(() => {
     if (!polygon) return null;
     return { type: 'Feature', geometry: polygon, properties: {} };
   }, [polygon]);
 
+  const mapRef = useRef<MapRef>(null);
+
+  // Drive camera flights from outside. Re-fires whenever cameraTarget.key
+  // changes — pick any monotonic number (Date.now() works) when invoking.
+  useEffect(() => {
+    if (!cameraTarget) return;
+    const map = mapRef.current;
+    if (!map) return;
+    const reduced =
+      typeof window !== 'undefined' &&
+      window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+    map.flyTo({
+      center: [cameraTarget.lng, cameraTarget.lat],
+      zoom: cameraTarget.zoom ?? Math.max(viewState.zoom, 15),
+      duration: reduced ? 0 : 1200,
+      essential: true,
+    });
+    // We intentionally exclude viewState.zoom from the dep list — we want
+    // this effect to fire only when cameraTarget changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [cameraTarget]);
+
   const handleContextMenu = (e: MapLayerMouseEvent) => {
     // Suppress the native browser context menu over the map canvas.
     e.originalEvent?.preventDefault();
@@ -77,6 +107,7 @@ export function IlsochroneMap({
 
   return (
     <Map
+      ref={mapRef}
       mapStyle={tileStyle.styleUrl}
       attributionControl={false}
       longitude={viewState.longitude}

apps/web/src/components/map/PoiLayer.tsx

@@ -3,23 +3,16 @@
 /**
  * PoiLayer — renders POI markers on the map.
  *
- * Responsibilities:
- *   - Filter incoming POIs to those inside the isochrone polygon (since the
- *     fetch was scoped to the bbox, which is a superset).
- *   - Render one Marker per POI, with a category-coloured dot.
- *   - On marker click, emit `onSelect(poi)` so the page can show the
- *     DestinationCard at the right place.
+ * Dumb renderer: the parent passes already-visible POIs (i.e. inside the
+ * isochrone polygon) and we just draw them. Polygon clipping lives in
+ * page.tsx so "Surprise me" and the layer share the same visible set.
  */
-import { useMemo } from 'react';
 import { Marker } from 'react-map-gl/maplibre';
-import type { Polygon, MultiPolygon } from 'geojson';
 import type { Poi, PoiCategory } from '@ilsochrone/providers';
-import { isInsidePolygon } from '@/lib/polygon';
 import { cn } from '@/lib/utils';
 
 interface Props {
   pois: Poi[];
-  polygon?: Polygon | MultiPolygon;
   onSelect: (poi: Poi) => void;
   /** When set, render the selected POI marker emphasized. */
   selectedId?: string;
@@ -34,15 +27,10 @@ const CATEGORY_COLORS: Record<PoiCategory, string> = {
   beach: 'bg-cyan-500',
 };
 
-export function PoiLayer({ pois, polygon, onSelect, selectedId }: Props) {
-  const visible = useMemo(() => {
-    if (!polygon) return pois;
-    return pois.filter((p) => isInsidePolygon([p.lngLat[0], p.lngLat[1]], polygon));
-  }, [pois, polygon]);
-
+export function PoiLayer({ pois, onSelect, selectedId }: Props) {
   return (
     <>
-      {visible.map((p) => (
+      {pois.map((p) => (
         <Marker
           key={p.id}
           longitude={p.lngLat[0]}

docs/FIRST-RUN.md

@@ -80,6 +80,8 @@ Copy the URL, paste in a new tab — same view.
 
 POI markers (parks, cafés, restaurants, museums, viewpoints, beaches) render inside the polygon. Toggle categories from the panel under the time/mode controls. Click a marker → same destination card as right-click, with the POI's name pre-filled.
 
+The **Surprise me** button picks a random reachable POI, flies the camera there, and opens the destination card. Disabled when no POIs are visible (toggle a category or expand time). Animation respects `prefers-reduced-motion`.
+
 ## 6. Known gaps (intentional)
 
 These land in subsequent tasks:

docs/TASKS.md

@@ -85,6 +85,18 @@ Conventions:
 - **Files.** `apps/web/src/app/opengraph-image.tsx`, `README.md`, `docs/screenshots/`.
 - **DoD.** OG card validates on opengraph.xyz. README links to the live URL.
 
+### T-16 · POI accuracy phase 1 — Foursquare adapter + CompositePoiProvider
+- **Goal.** Land a `FoursquarePoiProvider` in `packages/providers/src/poi/foursquare.ts`. Introduce `CompositePoiProvider` that routes commercial categories (café, restaurant) to Foursquare and geographic categories (park, beach, viewpoint, museum) to Geoapify, per ADR-0006.
+- **Files.** `packages/providers/src/poi/{foursquare,composite}.ts`, `packages/providers/src/poi/foursquare.test.ts` (fixture-driven), `apps/web/src/app/api/pois/route.ts` (swap to composite when key present), `apps/web/.env.example` (add `FOURSQUARE_API_KEY`).
+- **DoD.** Unit tests cover the routing logic. With `FOURSQUARE_API_KEY` set, café/restaurant markers come from Foursquare; without it, the existing Geoapify-only path still works.
+- **Blocked by.** User provisioning a Foursquare developer account.
+
+### T-17 · Suggested-places panel (sortable)
+- **Goal.** Side panel listing the visible POIs with sortable columns: rating (Foursquare/Google), distance from origin (computed client-side), category. Selecting a row opens the destination card and flies the camera (reusing the SurpriseMe camera path).
+- **Files.** `apps/web/src/components/panels/SuggestedPlaces.tsx`, small distance helper in `apps/web/src/lib/geo.ts`.
+- **DoD.** Toggling sort columns reorders the list instantly. Selecting a row updates the map. Works on mobile (panel collapses to a bottom sheet).
+- **Blocked by.** T-16 (needs rating data).
+
 ### T-15 · Production cutover
 - **Goal.** Promote latest preview to production. Tag `v0.1.0`. Post-mortem note: what worked, what didn't, what changed in the PRD.
 - **Files.** `CHANGELOG.md`, `docs/postmortem-v0.1.md`.

docs/adr/0006-poi-provider-strategy.md

@@ -0,0 +1,92 @@
+# ADR-0006: POI provider strategy — hybrid by category, phased rollout
+
+- Status: Accepted (decision); Implementation deferred until user is ready to provision accounts
+- Date: 2026-05-11
+- Deciders: Tomer
+
+## Context
+
+ADR-0003 chose **Geoapify Places** (OSM-sourced) as the MVP POI provider. After a week of real-world use, an accuracy gap is visible: the user reports specific Tel Aviv places — cafés, restaurants, small businesses — that exist in the city but are missing from the map. This isn't a Geoapify bug; it's an OSM coverage gap. Commercial venue density on OSM has historically lagged commercial map products (Google, Foursquare, Apple) by years, especially outside major Western European cities.
+
+The user also wants to add a "suggested places" panel sortable by user-configurable parameters (popularity, rating, distance). OSM data does not include rating/popularity signals at scale; commercial APIs do.
+
+## Decision
+
+Adopt a **hybrid POI sourcing strategy**, with implementation phased to track when external accounts are available.
+
+### Category routing
+
+Split categories by where the data lives best:
+
+| Category | Best source | Why |
+|---|---|---|
+| Park | OSM (Geoapify) | OSM excels at physical geography; parks are well-mapped. |
+| Beach | OSM (Geoapify) | Same. |
+| Viewpoint | OSM (Geoapify) | Volunteer mappers love viewpoints. |
+| Museum | OSM (Geoapify) or commercial | Static, well-known set; either works. |
+| Café | Foursquare or Google | Commercial venue churn; OSM gaps are biggest here. |
+| Restaurant | Foursquare or Google | Same as café. |
+
+The mapping lives in code as `CATEGORY_TO_PROVIDER`. UI and the rest of the app see one normalized `Poi[]` and don't know which provider produced which marker.
+
+### Architecture
+
+Introduce a `CompositePoiProvider` that wraps multiple sub-providers and routes requests by category:
+
+```ts
+class CompositePoiProvider implements PoiProvider {
+  constructor(private byCategory: Partial<Record<PoiCategory, PoiProvider>>) {}
+
+  async searchInBbox(q: PoiQuery): Promise<PoiResult> {
+    const groups = groupBy(q.categories, (c) => this.byCategory[c]);
+    const results = await Promise.all(
+      [...groups.entries()].map(([provider, cats]) =>
+        provider?.searchInBbox({ ...q, categories: cats }),
+      ),
+    );
+    return mergeResults(results);
+  }
+}
+```
+
+The route handler instantiates this at startup based on env-var configuration. Single-provider deployments (e.g. "Geoapify only") work without `CompositePoiProvider` by passing the single provider directly.
+
+### Provider preference
+
+Among the commercial options, **Foursquare > Google** as the default upgrade for this project:
+- 100k req/mo free tier vs. Google's $200/mo credit (~10k Nearby Search calls). Foursquare is 10× cheaper at scale.
+- No credit card required for Foursquare's free tier.
+- Permissive ToS — fewer restrictions on caching and display than Google.
+- Comparable venue data quality in dense urban areas, including Tel Aviv.
+
+Google remains a credible second choice and may eventually be added as a third adapter for direct comparison. Apple Maps Server API is excluded (requires paid Apple Developer Program).
+
+### Phasing
+
+- **Phase 0 (now).** Geoapify only. CompositePoiProvider not yet introduced. Accuracy gap documented; user is informed.
+- **Phase 1 (when user provisions Foursquare).** Add `FoursquarePoiProvider`, introduce `CompositePoiProvider`, route commercial categories to Foursquare while keeping geographic categories on Geoapify. Add `FOURSQUARE_API_KEY` to `.env.example`.
+- **Phase 2 (optional).** Add `GooglePoiProvider` for comparison. Could be selected per category, or A/B'd against Foursquare via a feature flag.
+- **Phase 3 (suggested-places panel).** Build the side panel that lists POIs with sortable columns (rating, distance, category). Rating is sourced from Foursquare/Google; distance is computed client-side from `state.origin`; category is already in the `Poi` shape. The panel reuses the existing `PoiProvider` data path — no new provider work needed.
+
+## Why not just add Foursquare now
+
+The user explicitly opted out of provisioning new external accounts this round. Building a Foursquare adapter without an active Foursquare account means landing untested code in the repo, then either:
+
+- Mocking the upstream and relying on integration tests we don't have, or
+- Leaving the code in a "compiles but never ran" state — high risk of subtle bugs when it eventually does run.
+
+Better to write the design now (this ADR + a stub in TASKS.md), and implement when the account is in hand and the integration can be exercised end-to-end.
+
+## Consequences
+
+- Phase 0 ships with a known accuracy gap. The map will under-represent Tel Aviv's commercial venue density. We mitigate by showing the user we know.
+- The PRD's POI categories (FR-6) don't change — internal taxonomy is provider-agnostic on purpose.
+- Phase 1+ adds attribution requirements: any view that displays Foursquare data must show Foursquare attribution near the marker or in the destination card. ADR-0005's `DestinationCard` is the natural home.
+- The CompositePoiProvider pattern is a clean teaching moment for the abstraction: multiple adapters behind one interface, routing by domain key (category) without UI awareness. Worth highlighting in the README screenshots/walkthrough.
+- Cost ceilings: even Phase 2 (Google) stays inside Google's $200/mo credit for portfolio-level traffic.
+
+## When this ADR should be reopened
+
+- If Foursquare's free tier changes meaningfully (currently 100k req/mo).
+- If OSM coverage in Tel Aviv improves to the point that the gap closes (track via spot checks every few months).
+- If the user decides to go all-in on Google Maps for the UI overall (e.g. switching basemap to Google Maps tiles) — at which point a single-provider Google adapter becomes the simpler default.

docs/research/01-data-sources.md

@@ -68,7 +68,7 @@ The community-run `overpass-api.de` has been timing out under sustained scraper
 **Walking MVP (now):**
 - Isochrone engine: **OpenRouteService**
 - Basemap: **Stadia Maps** + MapLibre GL JS
-- POIs: **Geoapify Places**, with an Overpass (Private.coffee mirror) adapter behind the same interface for raw-query escape hatches
+- POIs: **Geoapify Places** (accuracy gap acknowledged; see ADR-0006 for the hybrid Foursquare/Google plan when the user is ready to provision accounts). Overpass (Private.coffee mirror) remains available behind the same interface as an escape hatch.
 - Architecture: four provider interfaces — `IsochroneProvider`, `PoiProvider`, `TileProvider`, and (phase-2) `TransitDataProvider` — each with at least one MVP adapter and a clear contract. No provider-specific types leak into UI components.
 
 **Phase 2 (transit):**