Application Shell & Navigation
Relevant source files
The following files were used as context for generating this wiki page:
The Application Shell in mdeapp provides a specialized "AI-first, chat-first, map-first" interface designed for discovering services in Medellín. It serves as the primary structural container that coordinates the AI chat interface (powered by CopilotKit), interactive maps, and navigation elements across different device form factors.
Sources: README.md:3-5, src/components/chat/geo-chat-shell.tsx:64
Core Shell Architecture
The application utilizes a GeoChatShell as its primary entry point, which orchestrates various providers for state management, including chat workflows, rental UI, and search results. The shell is built on Next.js 16 and React 19, utilizing a root layout that wraps the application in MdeAppProviders and MdeCopilotKitProvider.
Sources: src/app/layout.tsx:43-53, src/components/chat/geo-chat-shell.tsx:66-79
Component Hierarchy
The following diagram illustrates the high-level component structure within the GeoChatShell:
The shell is responsible for mounting global overlays such as VenueDetailSheet, CafeBookingSheet, and ScheduleViewingModal, ensuring they are accessible regardless of the current chat state.
Sources: src/components/chat/geo-chat-shell.tsx:80-111
Navigation Systems
The application implements a multi-tiered navigation strategy that adapts to desktop and mobile environments.
Chat Navigation Rail
On desktop devices, the ChatNavRail is a persistent sidebar component. It provides access to:
- Thread Management: Starting a new chat or switching between existing threads.
- Explore: Direct links to vertical-specific discovery pages (Restaurants, Cafes, Nightlife, Rentals, Events).
- Library: User-specific sections like Saved items and Tickets.
Sources: src/components/chat/chat-nav-rail.tsx:28-42, src/components/chat/chat-nav-rail.tsx:90-140
| Feature | Description | File |
|---|---|---|
| New Chat | Clears active thread and resets session | chat-nav-rail.tsx |
| Thread List | Displays recent AI conversations with loading skeletons | chat-nav-rail.tsx |
| Coming Soon | Placeholder tooltips for unreleased features (Trips, Profile) | chat-nav-rail.tsx |
Responsive Adaptive Navigation
The shell transitions between a persistent rail and a drawer-based system based on the viewport size.
- Desktop (>= 1024px): The navigation rail is visible as a sidebar.
- Mobile (< 1024px): The rail is hidden and replaced by a hamburger menu (
NAV_TRIGGER) that opens aChatNavDrawer. - Map Interaction: On mobile, a Floating Action Button (FAB) triggers a map sheet, whereas desktop shows the map in a side panel.
Sources: e2e/screens/SCREEN-018-mobile-shell.spec.ts:25-30, e2e/screens/SCREEN-018-mobile-shell.spec.ts:98-105
Layout Patterns
Browse Layout
For discovery pages outside the main chat (e.g., /cafes), the BrowseLayout provides a consistent header with a back button, filtering controls, and a results area. It is designed to maintain a "back to chat" link to return the user to the primary AI concierge.
Sources: src/components/browse/BrowseLayout.tsx:21-45
Implementation Detail: Mobile Constraints
Specific CSS overrides in globals.css ensure the shell functions correctly on mobile devices, particularly for iOS Safari.
- Input Scaling: Font size is set to
1remto prevent automatic zooming on focus. - Touch Targets: Control buttons maintain a minimum
44x44pxtarget size. - Safe Areas: Padding is adjusted for the iOS home indicator using
env(safe-area-inset-bottom).
Sources: src/app/globals.css:126-140
Summary
The Application Shell & Navigation system effectively bridges the gap between a traditional SaaS layout and an AI-driven interface. By using a responsive shell that manages both persistent navigation and contextual overlays (like map sheets and detail panels), the application ensures that the Medellín discovery experience remains fluid across desktop and mobile devices.