Wander AI documentation

Wander AI is an AI-powered travel itinerary platform. The product is shipped as a monorepo with two independent sub-projects:

• Admin panel (admin/) — a Next.js dashboard plus the mobile REST API at /api/mobile/*.
• Mobile app (apps/) — a Flutter iOS and Android client that consumes the mobile API.

They share no code and no JS workspace manager. Each one has its own toolchain, dependencies, and .env. This guide covers both halves.

Repository structure

wander-ai/
├── admin/        Next.js admin panel + /api/mobile/* REST endpoints
├── apps/         Flutter mobile client (iOS + Android)
├── docs/         This documentation
├── CLAUDE.md     Engineering notes (for Claude Code)
├── README.md     Quick-start
└── package.json  Root convenience scripts (no dependencies)

Root convenience scripts (run from repo root):

npm run dev:admin          # Next.js dev server
npm run build:admin        # Next.js production build
npm run dev:app            # flutter run (in apps/)
npm run analyze:app        # flutter analyze
npm run gen:app            # build_runner codegen
npm run build:app:android  # Android release APK
npm run build:app:ios      # iOS release build

A comprehensive administrative dashboard for managing the Wander AI platform. It provides tools for user management, trip monitoring, promotional content management, and system configuration. Built with Next.js, Shadcn UI, and Drizzle ORM.

Key features

• Dashboard overview: real-time analytics and system status.
• Admin users: manage admin accounts and secure access.
• App user management New: searchable, paginated list of mobile users with per-user detail (recent trips, Concierge Chat history, likes given), one-click Comp Pro toggle, and cascade-safe delete — replaces every “open Drizzle Studio” support workflow.
• Trip management: oversee user-generated trips, AI itineraries, and budgets.
• Promoted destinations: manage featured locations shown in the mobile app.
• Prompt tuner: edit the system prompts that drive both itinerary generation and the new Concierge Chat refinement (loaded from settings.system_prompt and settings.refine_system_prompt).
• API key management: manage OpenAI / Gemini / Google Maps / OpenWeatherMap keys from the UI. Honors a IS_DEMO=true env flag — when set, real key values are never sent to the client and editing is disabled with a teal “Demo mode” banner (server-side mutations are also blocked).
• Settings management: configure dynamic app settings directly from the UI.
• Modern UI/UX: clean interface using Shadcn UI components and Tailwind CSS.

Tech stack

Prerequisites

• Node.js 24 — declared in admin/package.json (engines.node: "24.x"). Vercel reads the same field, so local and deployed builds match. Node 22 still runs the panel, but npm install prints an engine warning.
• npm (a package-lock.json is included)
• PostgreSQL database (e.g., NeonDB)

Installation

1. 01
   Open a terminal in the repo root.
2. 02

   Install admin dependencies:

   terminalCopy

   npm --prefix admin install

Create a file named .env inside the admin/ directory and configure the following variables:

DATABASE_URL=
AUTH_SECRET=
BLOB_READ_WRITE_TOKEN=
MOBILE_API_KEY=
AI_PROVIDER=
JWT_SECRET=
OPENWEATHERMAP_API_KEY=
# IS_DEMO=true  public demo deployments only

Wander AI provides weather forecasts for trip destinations using the OpenWeatherMap One Call API 3.0.

Get an API key

1. 01
   Create a free account at openweathermap.org.
2. 02
   Navigate to API keys in your dashboard and copy your key.
3. 03
   Subscribe to the One Call API 3.0 plan (free tier includes 1,000 calls/day). A basic OWM key alone will not work.

Configure the key

• Admin panel (recommended): go to API Key Management and enter your key in the OpenWeatherMap API Key field.
• Environment variable (fallback): set OPENWEATHERMAP_API_KEY in admin/.env. Admin panel value takes priority.

How it works

• Mobile app calls GET /api/mobile/weather?lat=...&lng=...&startDate=...&endDate=....
• Backend proxies the request to OpenWeatherMap, keeping the API key off the device.
• Returns up to 8 days of daily forecast (temperature, conditions, humidity) filtered to the requested range.
• If trip dates are more than 8 days in the future, no forecast data is returned.

The admin panel uses Drizzle ORM with a PostgreSQL database. Migrations live in admin/drizzle/. Manage them via npx drizzle-kit push / npx drizzle-kit generate / npx drizzle-kit studio.

Development mode

npm run dev:admin
# or, from inside admin/
npm run dev

The app will be available at http://localhost:3000.

Production mode

npm run build:admin
npm --prefix admin start

Changing the app name

1. 01
   Open admin/package.json and update the "name" field.
2. 02
   Update the metadata title in admin/app/layout.tsx.

Changing colors

1. 01
   Open admin/app/globals.css.
2. 02
   Locate the :root block.
3. 03
   Update the --primary HSL value (default 175 33% 31%, teal).

WanderAI is an intelligent travel-planner mobile app. It leverages Generative AI and the Google Places API to create detailed, visual itineraries.

Key features

Trip details and refinement

The active itinerary screen and any owned saved trip surface a Refine ✦ floating pill (next to or replacing the Save Trip FAB). Tapping it opens the Concierge Chat sheet at 75% height, hydrates prior messages from GET /api/mobile/trips/:id/messages, and lets the user converse with the same OpenAI / Gemini engine that generated the trip. Refinements are saved server-side to the new trip_messages table; previous-snapshot rollback gives an instant Undo without losing the conversation.

• Flutter 3.44 or newer (Dart 3.12+) — required by GoRouter 18. Built and tested on Flutter 3.47 / Dart 3.13.
• Android Studio / VS Code, with the Android SDK Platform 37 installed
• Xcode and CocoaPods for iOS builds

Platform targets

Install dependencies

cd apps
flutter pub get

Configure environment (dart-define)

The mobile app uses Flutter’s --dart-define-from-file for build-time configuration — no .env loader, no runtime asset, no async init. Values resolve to compile-time constants via String.fromEnvironment and are centralized in apps/lib/core/config/env.dart.

Copy apps/env/example.json to apps/env/dev.json (gitignored) and fill in your values:

{
  "WANDER_API_KEY": "your_api_key_here",
  "GOOGLE_CLIENT_ID": "your_google_client_id_here",
  "REVENUECAT_API_KEY_IOS": "appl_...",
  "REVENUECAT_API_KEY_ANDROID": "goog_...",
  "USE_MOCK_IAP": true,
  "ENABLE_ADMOB": false,
  "BOOKING_AFFILIATE_ID": "",
  "SKYSCANNER_AFFILIATE_ID": "",
  "GETYOURGUIDE_PARTNER_ID": ""
}

WanderAI uses RevenueCat for In-App Purchases and Subscriptions. You need a RevenueCat project linked to your App Store and Google Play apps.

1. 01
   Create a RevenueCat account.
2. 02
   Create a new project for your app.
3. 03

   Critical — configure entitlements, offerings and products

   • Create an Entitlement identifier named pro (lowercase).
   • Create an Offering (typically named default) and attach your products to it.
   • Ensure your Google Play / App Store product IDs match exactly what you enter in RevenueCat. See setup guides for iOS and Android.
4. 04
   Get your API keys from RevenueCat (one per platform).
5. 05

   Add them to apps/env/dev.json (or prod.json):

   apps/env/dev.jsonCopy

   {
     "REVENUECAT_API_KEY_IOS": "appl_YOUR_IOS_KEY",
     "REVENUECAT_API_KEY_ANDROID": "goog_YOUR_ANDROID_KEY",
     "USE_MOCK_IAP": false
   }

Set USE_MOCK_IAP=true to test the UI without real store connections.

Pro users open Export as PDF from the “more actions” sheet on the itinerary or trip details screen. The preview screen offers Share and Print through the OS. Everything is rendered on the device, so there is no endpoint to deploy and no key to configure.

What’s in the file

• Cover: trip photo, destination, dates, and travellers / budget chips.
• Bookings grouped by date, then the day-by-day itinerary (time, place, type, description, photo, and a tappable Open in Maps link), then the packing list with checkboxes.
• Page-numbered footers, in the app’s own font and colours. Page size is US Letter for US/CA/MX/PH locales and A4 everywhere else.

Where to customise it

Each trip details screen surfaces two booking CTAs (Hotels via Booking.com, Flights via Skyscanner), pre-filled with the trip’s destination and dates. Every activity bottom sheet adds a Find Tours & Tickets CTA that searches GetYourGuide by place name. The URL builders live in apps/lib/core/services/affiliate_service.dart; swap partners or tweak query params there.

Wiring partner IDs

1. 01
   Sign up for the partner programs you want to monetize — Booking.com Affiliate Partner, Skyscanner Partners, GetYourGuide Partner.
2. 02

   Once approved, copy your IDs into apps/env/dev.json (and prod.json):

   apps/env/prod.jsonCopy

   {
     "BOOKING_AFFILIATE_ID": "1234567",
     "SKYSCANNER_AFFILIATE_ID": "your_associate_id",
     "GETYOURGUIDE_PARTNER_ID": "your_partner_id"
   }

3. 03
   Rebuild with --dart-define-from-file=env/prod.json. Every CTA tap now carries your attribution.

Analytics and conversion tracking

CTA taps emit an affiliate_cta_clicked event with partner, kind, destination, trip_id, place_name, and activity_type properties. The mobile app POSTs events to the admin’s POST /api/mobile/analytics route, which validates the payload with Zod and forwards it to Vercel Analytics via @vercel/analytics/server (auto-tagging source: "mobile").

Find the data in your Vercel project → Analytics → Events. Filter by event name and slice by partner / kind / destination to compare which booking surfaces drive the most clicks.

To track any other mobile event, call AnalyticsService.track('your_event_name', properties: { ... }) from anywhere in the Flutter code — it’s fire-and-forget and never throws.

The mobile app follows a feature-first architecture for scalability.

apps/lib/
├── core/               Core utilities, theme, router, shared services
├── features/           Feature-based modules
│   ├── auth/           Authentication (email, Google, Apple)
│   ├── bookings/       Flights, hotels and reservations per trip
│   ├── community/      Public trip feed
│   ├── expense/        Trip expense tracker
│   ├── explore/        Discovery / home screen
│   ├── onboarding/     Vibe-check onboarding flow
│   ├── packing/        Packing list per trip
│   ├── pdf_export/     Pro: trip PDF (builder, preview, share/print)
│   ├── refine/         Concierge Chat refinement
│   ├── settings/       App settings (theme, etc.)
│   ├── shell/          Main navigation shell
│   ├── subscription/   RevenueCat paywall
│   ├── trip/           Trip generation, itinerary, saved trips
│   └── weather/        Forecast for trip days
└── main.dart           Application entry point

Unit tests live in apps/test/, mirroring the same structure. Run them with cd apps && flutter test.

Changing the app name

Update the name field in apps/pubspec.yaml. For the display label on the home screen, edit apps/android/app/src/main/AndroidManifest.xml and apps/ios/Runner/Info.plist.

Changing the primary color

1. 01
   Open apps/lib/core/theme/app_theme.dart.
2. 02
   Find the MaterialTheme class.
3. 03
   Update primary in the lightScheme and darkScheme methods.

// Example in app_theme.dart
static ColorScheme lightScheme() {
  return const ColorScheme(
    brightness: Brightness.light,
    primary: Color(0xff356668),  // <-- change this HEX
    // ... other colors
  );
}

Pass your environment file with --dart-define-from-file. For convenience, add the flag to your IDE’s launch configuration (VS Code: .vscode/launch.json, Android Studio: Edit Configurations → Additional run args).

Android

cd apps
flutter run --dart-define-from-file=env/dev.json

iOS

cd apps/ios
pod install
cd ..
flutter run --dart-define-from-file=env/dev.json

flutter config --no-enable-swift-package-manager
cd apps/ios && rm -rf Pods Podfile.lock && pod install && cd ..

Production builds

flutter build apk       --dart-define-from-file=env/prod.json
flutter build appbundle --dart-define-from-file=env/prod.json
flutter build ios       --dart-define-from-file=env/prod.json

Every version published so far. Updates are free for the life of the item.

If you need any assistance, have questions, or want to report a bug, please contact us:

What support covers

• Six months of support from purchase, extendable at checkout
• Support covers bugs in the template and questions about how it is put together
• It does not cover custom feature work, third-party API changes or store review outcomes
• The Regular licence covers one free end product. Charging users for the app itself needs the Extended licence