"I want to do some sightseeing focused on history, 2 hours" → The app plans a route, guides you turn-by-turn, and narrates as you walk.
GuideMe is a real-time AI walking tour guide that creates personalised city tours based on your interests and available time. Unlike static audio guides, it actively navigates you through the city with voice narration — and reacts to your current location in real time.
- Flexible Input — Choose a start location, end location, and exploration region
- Theme Selection — 6 tour themes: History · Architecture · Art & Culture · Food & Drinks · Parks & Nature · Local Secrets
- Duration Picker — 30 min · 1 h · 1.5 h · 2 h · 3 h
- AI-powered Route Generation — Powered by Groq LLM + Google Places API to find and rank the best POIs for your preferences
- Interactive Map — Full-screen Mapbox GL map with numbered stop markers and route polyline
- Stop Details — Each stop shows name, description, and AI-generated narration
- Tour Overview — Ordered stop list with duration and stop count
- Text-to-Speech Narration — Google TTS reads out descriptions when you arrive at a stop
- Speech Recognition — Web Speech API for voice input (ask questions hands-free)
- Speech Synthesis Fallback — Browser-native synthesis if Google TTS is unavailable
- Geolocation Hook — Real-time GPS tracking with permission handling
- Proximity Detection — Automatically triggers narration when you approach a stop
- Live Position on Map — Your dot moves in real time
- Context-aware Q&A — Ask questions about the current stop during the tour
- Streaming responses via Groq API (llama-3.3-70b-versatile)
- NextAuth.js — Secure session management
- Google OAuth — Sign in with Google (configured via env)
| Layer | Technology | Purpose |
|---|---|---|
| Framework | Next.js 16 (App Router) | SSR, API routes, file-based routing |
| Language | TypeScript | Full type safety across frontend & backend |
| UI Library | Shadcn/UI + Radix UI | Accessible, composable component primitives |
| Styling | Tailwind CSS v4 | Utility-first styling with tw-animate-css |
| Maps | Mapbox GL JS | Interactive maps, route rendering, custom markers |
| Auth | Convex Auth + Google OAuth | Session management, OAuth |
| Database | Convex | User data, tours, favorites, preferences |
| AI / LLM | Groq API + Inception API | Tour generation, context-aware Q&A |
| AI SDK | OpenAI Node SDK | Provider client abstraction |
| Places Data | Google Places API | Point-of-interest discovery near a location |
| Voice Output | Google Text-to-Speech API | Natural voice narration at each stop |
| Voice Input | Web Speech API | Browser-native voice recognition |
| Icons | Lucide React | Consistent icon system |
guideme/
├── convex/ # Convex schema, auth, queries/mutations
├── src/
│ ├── app/
│ │ ├── api/
│ │ │ ├── chat/ # AI Q&A streaming endpoint
│ │ │ ├── tours/ # Tour generation/edit endpoints
│ │ │ └── tts/ # Text-to-Speech endpoint
│ │ ├── explore/ # Tour planner page
│ │ ├── tour/ # Active tour page
│ │ ├── login/ # Auth page
│ │ └── page.tsx # Landing / home
│ ├── components/
│ │ ├── map/ # MapboxMap, RouteMap components
│ │ ├── chat/ # ChatPanel, ChatMessage
│ │ ├── tour/ # Tour-related UI components
│ │ └── ui/ # Shadcn/Radix primitive wrappers
│ ├── hooks/
│ │ ├── use-geolocation.ts # GPS tracking hook
│ │ ├── use-proximity.ts # Stop proximity detection
│ │ ├── use-speech-recognition.ts
│ │ └── use-speech-synthesis.ts
│ ├── lib/
│ │ ├── ai-provider.ts # Provider switch (Groq/Inception)
│ │ ├── inception.ts # Inception API integration
│ │ ├── google-tts.ts # Google TTS integration
│ │ ├── places.ts # Google Places API wrapper
│ │ ├── convex.ts # Convex client setup
│ │ └── utils.ts # Shared utilities
│ └── proxy.ts # Auth-aware request proxy helpers
└── public/
└── screenshots/ # App screenshots
- Node.js 18+
- Convex account/deployment (for auth + persistence)
- API keys (see below)
# Clone the repo
git clone https://github.com/maxuhrlaß/guideme.git
cd guideme
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env
# → Fill in your API keys
# Optional: run Convex locally (auth + persistence)
npx convex dev
# Run the development server
npm run devOpen http://localhost:3000.
Create a .env file in the project root based on this template:
# Database
DATABASE_URL="postgresql://user:password@localhost:5432/guideme?schema=public"
# NextAuth.js
AUTH_SECRET="your-secure-secret"
AUTH_URL="http://localhost:3000"
# OAuth (optional)
AUTH_GOOGLE_ID=""
AUTH_GOOGLE_SECRET=""
# AI provider: "inception" or "groq"
AI_PROVIDER="inception"
# AI Provider (Inception)
INCEPTION_API_KEY="your-inception-api-key"
# AI Provider (Groq)
GROQ_API_KEY="your-groq-api-key"
# Maps
NEXT_PUBLIC_MAPBOX_TOKEN="your-mapbox-token"
# Places API
GOOGLE_PLACES_API_KEY="your-google-places-key"
# Text-to-Speech
GOOGLE_TTS_API_KEY="your-google-tts-key"
# Convex (user history, favorites, preferences)
NEXT_PUBLIC_CONVEX_URL="https://<your-deployment>.convex.cloud"
CONVEX_DEPLOY_KEY="dev:<your-deploy-key>"
CONVEX_SITE_URL="your-convex-site-url"
⚠️ Never commit your.envfile. It is listed in.gitignoreby default.
- Offline map tile caching (PWA)
- Wake-word activation ("Hey GuideMe")
- Voice commands: "next stop", "tell me more", "pause"
- Tour history & saved favorites
- Multi-city support
- Freemium subscription model
Private project — all rights reserved.