NaviX

Voice-guided travel companion for exploring Sri Lanka — interactive maps, live weather, and AI-powered historical context powered by OpenAI with Gemini fallback.

• Live map — Google Maps with nearby heritage sites
• AI tour guide — Multi-agent Gemini pipeline (intent, weather, heritage, voice script)
• Voice interaction — Speech recognition and text-to-speech for hands-free touring
• Weather-aware tips — OpenWeather integration with location-based advice
• Destination discovery — Browse and search Sri Lankan landmarks
• Responsive UI — Vite + React with dark mode and mobile navigation

NaviX/
├── frontend/          # Vite + React SPA
│   ├── src/
│   │   ├── pages/     # Home, Map, Chat, Destinations, About, Contact
│   │   ├── components/
│   │   ├── context/   # Auth, Chat, Location, Weather, Theme
│   │   ├── hooks/     # Geolocation, speech, API retry
│   │   └── services/  # API client (ceygoApi.js)
│   └── public/        # SPA redirects for Cloudflare Pages
├── backend/           # Cloudflare Worker API
│   ├── src/
│   │   ├── index.ts   # Routes and handlers
│   │   ├── ai.ts      # Gemini multi-agent pipeline
│   │   ├── db.ts      # Cloudflare D1 queries (places + geo)
│   │   └── weather.ts
│   ├── migrations/    # D1 schema + seed SQL
│   └── scripts/       # Wrangler deploy, seed conversion, secret sync
├── data/
│   ├── mongodb/       # Legacy/exported place documents (migration source)
│   └── scripts/       # Data processing (planned)
└── .github/workflows/ # Deploy on push to main / developer

• Node.js 22+ (Wrangler 4 requires v22)
• Cloudflare account (Pages + Workers)
• Google AI Studio API key (Gemini)
• Google Cloud Maps API key
• OpenWeather API key (optional)

The fastest way to run the full stack locally with no manual setup.

• Docker 24+
• Docker Compose v2 (bundled with Docker Desktop)

cp .env.example .env
# Open .env and fill in at minimum:
#   GEMINI_API_KEY or OPENAI_API_KEY
#   VITE_GOOGLE_MAPS_API_KEY
#   VITE_GOOGLE_CLIENT_ID + GOOGLE_CLIENT_ID (same value)
#   ADMIN_BOOTSTRAP_TOKEN (any long random string)

docker compose up --build

The backend container automatically:

• Generates backend/.dev.vars from your .env variables
• Applies D1 SQLite migrations (local Miniflare mode)
• Starts Wrangler with live-reload on source changes

Hot-reload is enabled — changes to frontend/src/ and backend/src/ reflect immediately without rebuilding the image.

docker compose down

To also wipe the local D1 database volume:

docker compose down -v

Builds the React app as optimised static files served via nginx. The backend continues to run on Cloudflare Workers.

# Set your real Cloudflare Worker URL in .env first:
# VITE_API_BASE_URL=https://navix-api.<subdomain>.workers.dev

docker compose -f docker-compose.prod.yml up --build -d

Frontend is served at http://localhost:80.

docker-compose.yml          ← local dev
  frontend (Vite HMR)       port 5173
  backend  (Wrangler dev)   port 8787   ← Miniflare, local D1

docker-compose.prod.yml     ← production frontend only
  frontend (nginx)          port 80     ← serves built /dist
  backend  ──────────────────────────── runs on Cloudflare Workers

From the repo root:

npm install

cd backend
cp .dev.vars.example .dev.vars   # fill in secrets (see below)
npm run dev

API runs at http://localhost:8787

cd frontend
cp .env.example .env.local
npm run dev

App runs at http://localhost:5173

The admin panel route is GET /admin/users and requires a user with is_admin=1.

1. Set ADMIN_BOOTSTRAP_TOKEN:
   • Local dev: add it in backend/.dev.vars
   • Remote Worker: run cd backend && npx wrangler secret put ADMIN_BOOTSTRAP_TOKEN
2. Start backend (cd backend && npm run dev) so POST /admin/bootstrap is reachable.
3. Run this PowerShell command once to create your first admin credentials:

$body = @{
  token = "your-bootstrap-token"
  email = "admin@yourdomain.com"
  password = "UseAVeryStrongPassword123!"
  name = "Super Admin"
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "http://localhost:8787/admin/bootstrap" -ContentType "application/json" -Body $body

After the first admin is created, bootstrap is automatically disabled and returns 409 on future calls.

Base URL: https://navix-api.nethminamalshan5.workers.dev (production) or http://localhost:8787 (local).

{
  "message": "Tell me about this place",
  "lat": 7.957,
  "lng": 80.760,
  "weather_data": { "temp": 30, "condition": "Cloudy" }
}

Response includes structured agents: intent_agent, weather_agent, heritage_agent, and voice_script for TTS.

Database is now hosted in Cloudflare D1 and queried directly from the Worker.

1. Create the D1 database:
   • cd backend
   • npx wrangler d1 create navix-db
2. Copy the returned database_id into backend/wrangler.toml under [[d1_databases]].
3. Apply schema and seed migrations locally:
   • npm run d1:migrate:local
4. Apply migrations to remote D1:
   • npm run d1:migrate:remote
5. To convert Mongo-exported JSON into a D1 seed migration:
   • node ./scripts/mongo-to-d1-seed.mjs <input-json> <output-sql>
   • Example: npm run d1:seed:generate

cd backend
npm install
cp .dev.vars.example .dev.vars
npm run cf:login
npm run cf:secrets
npm run d1:migrate:remote

Register a workers.dev subdomain (first time): Cloudflare Dashboard → Workers → onboarding.

# From repo root — set VITE_API_BASE_URL in frontend/.env.local first
npm run deploy:all

Or separately:

npm run deploy:backend
npm run deploy:frontend

Production URLs:

• App: https://navix-frontend.pages.dev
• API: https://navix-api.nethminamalshan5.workers.dev

Pushes to main or developer trigger:

• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID
• VITE_GOOGLE_MAPS_API_KEY (optional)

• VITE_API_BASE_URL — e.g. https://navix-api.nethminamalshan5.workers.dev

Also add Worker secrets in the Cloudflare Dashboard (same keys as .dev.vars).

1. Place source documents in data/raw/
2. Run scripts in data/scripts/ to clean and format
3. Output goes to data/processed/ for ingestion into D1 places table

Private — team use only unless otherwise specified.