Kakao map provider + POI name search overlay

[malkoG]

Summary

Introduces a pluggable user-facing map provider abstraction (OSM default, Kakao, Google stub) driven by MAP_PROVIDER env, and adds a floating POI name-search overlay on top of the interactive maps that hits Kakao's local keyword search and focuses the map on the picked result. OSM/OSS builds get the existing Leaflet behavior unchanged; Kakao deployments get richer place discovery for organizers on /events/create + check-in flows on /places.

Closes #166 (core: provider abstraction + Kakao place search; reverse geocoding and modal UI mode remain as follow-ups). Also partially addresses #110 and #116 — full forward geocoding via Nominatim and an abstract geocoding interface are out of scope here.

---

Assisted-By: Claude Code(claude-opus-4-7)

Summary by CodeRabbit

Release Notes

• New Features

  • Added support for multiple map providers: OpenStreetMap (default), Kakao Maps, and Google Maps
  • Introduced map search overlay enabling point-of-interest searches biased by map location
  • Integrated POI search functionality across map views for enhanced place discovery

• Chores

  • Extended environment configuration for map provider selection and credentials

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR implements a multi-provider map abstraction layer with support for OSM (Leaflet), Kakao Maps, and Google Maps. It introduces environment-driven provider selection, new UserFacingMap component that dispatches to provider adapters, Kakao POI keyword search integration with client overlay and server-side caching, and updates existing map usages across pages and components to use the new abstraction.

Changes

Cohort / File(s)	Summary
Configuration & Environment .env.example, src/server/env.ts, src/components/maps/config.ts	Added environment variables for map provider selection (MAP_PROVIDER, KAKAO_MAP_APP_KEY, KAKAO_MAP_REST_KEY, GOOGLE_MAPS_API_KEY); exposed them via env object; created useMapConfig() hook to fetch /api/map-config with infinite stale time and no automatic retries.
Type Definitions & Utilities src/components/maps/types.ts, src/components/maps/icon.ts, src/server/services/poi-search/types.ts, src/lib/place.ts	Defined MapProvider, MarkerColor, MapMarker, CircleOverlay, UserFacingMapProps, MapConfig types; added buildMarkerArtwork(), buildSelectedPinArtwork(), and toDataUri() for SVG marker generation; introduced PoiCandidate, PoiSearchParams, PoiSearchError for search results; added zoomToRadius() utility mapping zoom levels to search radii.
Core Map Abstraction & Adapters src/components/maps/UserFacingMap.tsx, src/components/maps/index.ts, src/components/maps/adapters/LeafletAdapter.tsx, src/components/maps/adapters/KakaoAdapter.tsx, src/components/maps/adapters/GoogleAdapter.tsx	Created UserFacingMap that dispatches to provider-specific adapters based on runtime config; LeafletAdapter wraps LeafletMap; KakaoAdapter implements full Kakao map with marker management, zoom tracking, bounds fitting, geolocation, and resize observation; GoogleAdapter stub throws "not implemented" error.
Leaflet Refactoring src/components/LeafletMap.tsx	Consolidated marker/type definitions by re-exporting from maps/types; replaced local icon factories (makeIcon, makeSelectedPin) with buildMarkerArtwork() pipeline; simplified props to use UserFacingMapProps; updated GPS marker and icon placement logic.
Search & Place Discovery src/components/MapSearchOverlay.tsx, src/server/services/poi-search/index.ts, src/server/services/poi-search/kakao.ts, src/server/services/poi-search/types.ts, src/server/controllers/places/poi-search.ts	Added MapSearchOverlay component with debounced keyword search, radius computation from zoom level, dropdown UI, and candidate selection callback; implemented Kakao POI search backend with in-memory 5-minute LRU cache; added API controller to parse query parameters and delegate to search service.
Map Configuration Endpoint src/server/controllers/map-config/get.ts, src/server-entry.ts	Created /api/map-config endpoint returning provider and provider-specific keys; wired endpoint in server entry; updated CSP header to conditionally allow Kakao/Daum scripts when provider is Kakao.
Page & Component Integration src/routes/places/index.tsx, src/routes/places/$placeId/index.tsx, src/routes/events/$eventId/index.tsx, src/components/PlacePicker.tsx	Replaced LeafletMap with UserFacingMap across place listing, place detail, and event detail pages; added MapSearchOverlay to places listing for POI search; imported zoomToRadius from utility; updated PlacePicker to track zoom state and integrate search overlay; unified map usage to new abstraction.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant UserFacingMap
    participant useMapConfig
    participant MapConfigAPI as /api/map-config
    participant Adapter as Adapter<br/>(Kakao/Google/OSM)
    
    Client->>UserFacingMap: render with props
    UserFacingMap->>useMapConfig: fetch config
    useMapConfig->>MapConfigAPI: GET /api/map-config
    MapConfigAPI-->>useMapConfig: { provider, keys }
    useMapConfig-->>UserFacingMap: config & loading/error state
    
    alt config loading
        UserFacingMap->>UserFacingMap: render skeleton
    else config error
        UserFacingMap->>UserFacingMap: render error container
    else config ready
        UserFacingMap->>Adapter: dispatch based on provider
        Adapter->>Adapter: initialize & render map
        Adapter-->>Client: interactive map UI
    end

Loading

sequenceDiagram
    participant User
    participant MapSearchOverlay
    participant Client as Browser
    participant SearchAPI as /api/places/poi-search
    participant KakaoService as Kakao Service
    participant KakaoAPI as Kakao Local API
    
    User->>MapSearchOverlay: type query + focus
    MapSearchOverlay->>MapSearchOverlay: debounce 250ms
    MapSearchOverlay->>SearchAPI: GET with q, lat, lng, radius
    SearchAPI->>KakaoService: searchPois(params)
    
    alt cache hit
        KakaoService-->>SearchAPI: cached PoiCandidate[]
    else cache miss
        KakaoService->>KakaoAPI: keyword search request
        KakaoAPI-->>KakaoService: documents
        KakaoService->>KakaoService: normalize & cache
        KakaoService-->>SearchAPI: PoiCandidate[]
    end
    
    SearchAPI-->>MapSearchOverlay: { candidates }
    MapSearchOverlay->>MapSearchOverlay: render dropdown
    User->>MapSearchOverlay: click candidate
    MapSearchOverlay->>Client: onPick(candidate)
    Client->>Client: update form state

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• Introduce map picker component with pluggable provider abstraction (OSM / Kakao / Google) #166: This PR directly implements the map picker component with pluggable provider abstraction (OSM/Kakao/Google) as specified—adding MapProvider type enumeration, environment-driven configuration, provider-specific adapters, server-side configuration endpoint, and Kakao POI search integration.

Poem

🐰 Hoppy times for maps so fine,
Providers swapped with zero sign,
Kakao hops, Google glides, Leaflet stays,
One interface lights all the ways! 🗺️✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.52% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Kakao map provider + POI name search overlay' accurately captures the main changes: introduction of Kakao as a map provider option and a new search overlay component for discovering points of interest.
Linked Issues check	✅ Passed	The PR fulfills key requirements from issue #166: implements provider abstraction with MAP_PROVIDER environment variable, provides Kakao adapter alongside OSM default and Google stub, adds place search via MapSearchOverlay and /api/places/poi-search endpoint, and integrates map picker into relevant user-facing flows.
Out of Scope Changes check	✅ Passed	All changes align with the stated objectives. Map provider abstraction, Kakao integration, POI search implementation, and UI layer integration are all within scope. No unrelated refactoring or feature additions detected outside the PR objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/kakao-map-providwr

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}