Skip to content

README.md

Latest commit

 

History

History
329 lines (247 loc) · 11.6 KB

README.md

File metadata and controls

329 lines (247 loc) · 11.6 KB

🌀 Time Traveller - Visit Any Place, Any Era with AI

Time Traveller Gemini Motia Vercel

Travel anywhere in the world, across any time period. See yourself in history!

🚀 Live Demo • ⭐ GitHub • 📖 Docs

Time Traveller

🖼️ Screenshots


Complete UI
Authentication
AI Generation

Location Intelligence
Nearby Places
Terminal Mode

Motia Workbench
Motia Cloud
Request Tracing

✨ Key Features

Feature Description
🤖 AI Image Generation 2K photorealistic images via Gemini 3 Pro (Nano Banana)
🗺️ Street View Integration Real Google Maps imagery as AI context
🌦️ Location Intelligence Weather, air quality, nearby places
🔐 Secure Auth Google/GitHub OAuth via Supabase
🔒 Private History Your travel history is only visible to you
👤 Traveler Insertion Insert yourself into any scene
🎨 5 Art Styles Photorealistic, Cyberpunk, Renaissance, Impressionist, Baroque
🕰️ Any Era Ancient Rome to 2150+
⚡ Real-time Streaming Live progress via Motia Streams
🎙️ Audio Narration AI-generated voice descriptions

🚀 Quick Start

Prerequisites

Installation

git clone https://github.com/rohitg00/time-traveller.git
cd time-traveller
npm install

Configuration

Create .env in project root:

# AI & Maps
GEMINI_API_KEY=your_gemini_key
GOOGLE_API_KEY=your_google_maps_key
VITE_GOOGLE_API_KEY=your_google_maps_key

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key

# JWT
JWT_SECRET=your_secret
JWT_EXPIRATION=24h

Launch

# Terminal 1: Backend
npm run backend

# Terminal 2: Frontend
npm run dev
Service URL
App http://localhost:5173
API + Workbench http://localhost:3000

🎮 How to Use

Three Input Modes

Mode How It Works
📋 Manual Enter destination, era, style, upload photo
💻 Terminal Natural language: "Take me to Paris in 1889"
🌍 Orbital Click map, search address/pincode, see weather & places

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│              React Frontend (Vite)                   │
│                localhost:5173                        │
└─────────────────┬───────────────┬───────────────────┘
                  │               │
           REST API        WebSocket Streams
                  │               │
┌─────────────────▼───────────────▼───────────────────┐
│              Motia Backend Framework                 │
│                localhost:3000                        │
├─────────────────────────────────────────────────────┤
│  API Steps          │  Event Steps                  │
│  • /teleport        │  • GenerateImage              │
│  • /auth            │  • GenerateLocationDetails    │
│  • /history         │  • SynthesizeSpeech           │
│  • /location/info   │  • CompleteTeleport           │
└─────────────────────┴───────────────────────────────┘
                  │               │
          Gemini AI        Google Maps API

📡 API Reference

Endpoint Method Description
/teleport POST Start time travel
/teleport/:id GET Get progress/results
/teleport/:id/audio GET Get narration
/history GET User's travel history
/auth POST Exchange Supabase token
/user GET Get authenticated user
/location/info GET Weather, AQI, places
/parse-command POST Parse natural language

🧰 Tech Stack

Backend Frontend
Motia Framework React 19 + Vite
TypeScript + Zod Tailwind CSS
Redis Google Maps API
Gemini 3 Pro Supabase Auth
Supabase Storage WebSocket Streams

🚀 Deployment

Motia Cloud (Backend)

Option 1: GitHub Actions (Recommended)

Automatic deployment on every push to main:

  1. Add GitHub Secrets (Settings → Secrets → Actions):

    Secret Description Where to Get
    MOTIA_API_KEY Motia Cloud API key Motia Cloud → Settings → API Keys
    MOTIA_ENV_ID Environment ID Motia Cloud → Your Project → Settings
    GEMINI_API_KEY Google Gemini API key aistudio.google.com
    GOOGLE_API_KEY Google Maps API key Google Cloud Console
    SUPABASE_URL Supabase project URL supabase.com → Project Settings
    SUPABASE_KEY Supabase anon key Supabase → Project Settings → API
    SUPABASE_SERVICE_ROLE_KEY Supabase service role key Supabase → Project Settings → API
    JWT_SECRET Secret for signing JWTs Generate: openssl rand -base64 32
    GOOGLE_MAPS_MAP_ID Map ID for Advanced Markers Google Cloud Console

  2. Push to main - Deployment triggers automatically!

  3. Manual Deploy - Go to Actions → "Deploy to Motia Cloud" → "Run workflow"

# .github/workflows/deploy.yml - Already configured!
# Auto-generates version: v1.0.X based on commit count

Option 2: Manual via Workbench

  1. Start local backend: npm run backend
  2. Go to cloud.motia.dev
  3. Import from Workbench → Add env vars → Deploy

Option 3: CLI

npx motia cloud deploy \
  --api-key <MOTIA_API_KEY> \
  --project-name time-traveller \
  --environment-id <MOTIA_ENV_ID> \
  --version-name v1.0.0 \
  --env-file .env

Vercel (Frontend)

  1. Fork repo on GitHub
  2. Import to vercel.com/new
  3. Add environment variables:
    • VITE_API_URL = your Motia Cloud URL
    • VITE_WS_URL = your Motia Cloud WebSocket URL
    • VITE_GOOGLE_API_KEY
    • VITE_SUPABASE_URL
    • VITE_SUPABASE_ANON_KEY

🐛 Troubleshooting

Issue Solution
API key errors Check .env exists, restart backend
Street View unavailable Normal! AI generates without it
WebSocket failed Falls back to polling automatically
Frontend not loading Ensure both servers running
"Failed to authorize stream" errors Expected - Motia Workbench trying to connect before auth. Harmless, can be ignored. Only affects dev Workbench at :3000, not the app at :5173

📁 Project Structure

time-traveller/
├── frontend/           # React app
│   ├── components/     # UI components
│   ├── contexts/       # Auth context
│   └── assets/         # Static files
├── steps/              # Motia backend
│   ├── api/            # REST endpoints
│   ├── events/         # Background handlers
│   ├── middlewares/    # Auth middleware
│   └── streams/        # Real-time updates
├── services/           # Business logic
│   ├── gemini/         # AI services
│   ├── google/         # Maps APIs
│   └── supabase/       # Auth & storage
└── docs/img/           # Screenshots

🔒 Privacy & Data Storage

Your data is private and secure. Here's how we handle it:

Data Type Storage Access
Travel History Supabase Database Only you (authenticated)
Generated Images Supabase Storage Only you (via your history)
Audio Narrations Supabase Storage Only you (via your history)
Reference Photos Supabase Storage Only you (linked to your teleport)

How It Works

  • User Isolation: Each user's history is stored with their unique userId
  • Authenticated Access: History API requires valid JWT token
  • No Cross-User Access: You cannot see other users' travels, and they cannot see yours
  • Secure Storage: All images and audio are stored in private Supabase buckets
  • No Data Sharing: Your uploaded photos and generated content are never shared

💡 Note: When not logged in, history is stored locally in your browser's localStorage and is completely private to your device.

✨ What's New

  • 🔐 Supabase Auth - Google/GitHub OAuth with user isolation
  • 🔒 Private History - Each user only sees their own travels
  • 🌦️ Location Intelligence - Weather, AQI, nearby places
  • 🔍 Address Search - Search by pincode/address
  • 👤 Traveler Insertion - Insert yourself into scenes
  • ☁️ Cloud Storage - Images stored securely in Supabase
  • 🌈 Weather Animations - Dynamic background effects
  • 🎙️ Audio Playback - Play/abort audio narration controls

🤝 Contributing

Fork, experiment, and share your coolest time travels!

⭐ Star on GitHub

Built with Motia 💙 | Powered by Gemini 🍌

Made by Rohit Ghumare

GitHub stars