Interactive Map Experience
Relevant source files
The following files were used as context for generating this wiki page:
The Interactive Map Experience is a core pillar of the mdeai platform, providing a "map-first" discovery interface for Medellín. It integrates live geographic data with an AI concierge to help users find rentals, events, cafes, and nightlife. The system synchronizes the map's visual state with the AI's "working memory" to ensure that search results and map pins remain consistent during a conversation.
Sources: README.md:3-5, src/components/home/home-how-it-works.tsx:18-22
System Architecture
The map experience is built using @vis.gl/react-google-maps and @googlemaps/js-markerclusterer. It operates as part of a three-panel layout on desktop (navigation, chat, and map) and a responsive sheet-based layout on mobile.
Data Flow and Synchronization
A critical component of the architecture is the MapUiSync component, which pushes the current state of the map (pins, selected ID, and viewport) into the AI agent's state. This allows the AI to "see" what the user is looking at on the map.
The synchronization logic rounds viewport coordinates to 5 decimal places and debounces updates by 300ms to prevent excessive state transitions.
Sources: README.md:18, src/components/copilot/map-ui-sync.tsx:10-38, e2e/maps-layout-desktop.spec.ts:16-25
Component Breakdown
Map Display and Interaction
The interface uses several specialized panels to display details about venues discovered through the map.
| Component | Description | Test ID |
|---|---|---|
CafeDetailPanel | Displays detailed information about cafes, including hours, address, and booking CTAs. | cafe-detail-panel |
NightlifeDetailPanel | Shows nightlife venue specifics, safety notices, and music/dress code details. | nightlife-detail-panel |
MapRefererHelp | Troubleshooting component for Google Maps API authentication errors (Billing, Referrer, Activation). | map-referer-help |
SiblingRail | A horizontal scroll of other results from the same search to allow quick switching between pins. | cafe-sibling-rail |
Sources: src/components/cafe/cafe-detail-panel.tsx:160-165, src/components/nightlife/nightlife-detail-panel.tsx:112-117, src/components/maps/map-referer-help.tsx:12-15
Marker and Category Logic
Map pins are categorized by type, each with distinct visual glyphs and states.
- Grounded Pins: Represent verified locations (cafes, restaurants). They can be "muted" or visually altered if the venue is currently closed based on
openNowmetadata. - Rental Pins: Represent short-term rental options, typically using a home glyph.
- Event Pins: Represent cultural or entertainment events.
Sources: src/components/maps/markers/category-map-marker.test.ts:12-25, src/components/maps/markers/category-map-marker.test.ts:38-50
AI Integration and Grounding
The map experience is "grounded" in real-world data provided by Google Places and Mastra tools. When a user asks for recommendations, the system generates "Grounded Cards" in the chat which are linked to pins on the map.
Grounding Process Sequence
The following diagram illustrates how a user query results in synchronized map and chat updates:
Detail Panels and Actions
The detail panels (CafeDetailPanel, NightlifeDetailPanel) provide deep integration with Google Places data, including:
- Enrichment: Automatically fetching higher-resolution data like weekday descriptions and website URIs when a panel is opened.
- Deep Linking: Buttons for "Get Directions" (Google Maps) and "View Reviews".
- Booking: Integration with
openCafeBookingoropenNightlifeBookingto request visits.
// Example of merging search results with live enrichment data
function mergeDetail(card: CafeVenueDetail, enriched: any) {
return {
rating: enriched?.rating ?? card.rating,
openNow: enriched?.openNow ?? card.openNow,
photoNames: enriched?.photoNames?.length ? enriched.photoNames : [card.photoName],
// ... maps and directions URLs
};
}
Sources: src/components/cafe/cafe-detail-panel.tsx:32-55, src/components/nightlife/nightlife-detail-panel.tsx:125-135
Responsive Layouts
The system adapts the map experience based on the device viewport:
- Desktop (>=1280px): Three regions (Nav Rail, Center Chat, Right Map Panel) are visible simultaneously.
- Tablet: Center chat is visible with a Floating Action Button (FAB) to trigger the map sheet.
- Mobile: Uses a
map-sheet-trigger(FAB) to open the map as a full-screen overlay. The chat input remains accessible before and after the map sheet is displayed.
Sources: e2e/maps-layout-desktop.spec.ts:12-25, e2e/maps-layout-mobile.spec.ts:15-30, e2e/screens/SCREEN-018-mobile-shell.spec.ts:25-35
Summary
The Interactive Map Experience bridges the gap between conversational AI and geographic discovery. By synchronizing the map's viewport and selected entities with the ConciergeCoAgent, the system ensures that the AI assistant remains contextually aware of the user's spatial exploration. This integration, supported by robust detail panels and responsive design, provides a seamless discovery flow from "Ask" to "Map" to "Book".