• 🚀 Way Back Home

An immersive AI workshop platform where participants learn to build intelligent agents while rescuing a stranded space explorer.

Way Back Home is a hands-on workshop experience that teaches Google Cloud AI technologies through an engaging narrative. Participants crash-land on an alien planet and must use AI to identify themselves, analyze their surroundings, and coordinate rescue efforts.

🎮 The Experience

You're a space explorer whose ship has crashed on an uncharted planet. Your rescue beacon is offline, and you're scattered across the surface with other survivors. To get home, you must:

🛠️ Technology Stack

🚀 Quick Start

For Workshop Participants

1. Access Cloud Shell at console.cloud.google.com

2. Clone and setup:

   git clone https://github.com/google-americas/way-back-home.git
   cd way-back-home
   

3. Start with Level 0:

   ./scripts/setup.sh
   cd level_0
   

4. Follow the codelab: Level 0 Instructions

For Workshop Hosts

See Deployment Guide below for running your own instance.

📚 Documentation

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                           Way Back Home                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   Participant Journey                                                    │
│   ───────────────────                                                    │
│                                                                          │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐         │
│   │ Level 0  │───▶│ Level 1  │───▶│ Level 2  │───▶│ Level 3  │         │
│   │ Identity │    │ Location │    │   SOS    │    │  Rescue  │         │
│   └──────────┘    └──────────┘    └──────────┘    └──────────┘         │
│        │               │                                                 │
│        ▼               ▼                                                 │
│   ┌─────────────────────────────────────────────────────────────┐       │
│   │                    Backend API (Cloud Run)                   │       │
│   │  • Participant registration    • Evidence storage            │       │
│   │  • Location confirmation       • Event management            │       │
│   └─────────────────────────────────────────────────────────────┘       │
│        │               │                                                 │
│        ▼               ▼                                                 │
│   ┌──────────┐    ┌──────────┐    ┌──────────────────────────┐         │
│   │Firestore │    │ Firebase │    │      Frontend (Next.js)   │         │
│   │          │    │ Storage  │    │  • 3D planet visualization │         │
│   │• events  │    │• avatars │    │  • Real-time participant   │         │
│   │• users   │    │• evidence│    │    tracking                │         │
│   └──────────┘    └──────────┘    └──────────────────────────┘         │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

🌐 Deployment

Deploy Your Own Instance

1. Prerequisites:

   • Google Cloud project with billing enabled
   • Firebase project (Firestore + Storage + Auth)
   • Domain names (optional, for custom URLs)

2. Clone and configure:

   git clone https://github.com/google-americas/way-back-home.git
   cd way-back-home
   
   # Configure your project
   gcloud config set project YOUR_PROJECT_ID
   

3. Run infrastructure setup:

   ./scripts/setup-infrastructure.sh
   

4. Deploy all services:

   Note: On your first deployment, Cloud Run will generate unique URLs for your services. After the build finishes, you must redeploy the frontend once more using these specific URLs to ensure the 3D map can communicate with the API.

   # First deployment (to generate URLs)
   gcloud builds submit --config cloudbuild.yaml
   
   # Get and save your URLs
   export API_BASE_URL=$(gcloud run services describe way-back-home-api --format='value(status.url)')
   export MAP_BASE_URL=$(gcloud run services describe way-back-home-frontend --format='value(status.url)')
   
   # Redeploy frontend with the actual URLs
   gcloud builds submit --config cloudbuild.yaml \
     --substitutions=_API_BASE_URL=$API_BASE_URL,_MAP_BASE_URL=$MAP_BASE_URL,_DEPLOY_BACKEND=false
   

Environment Configuration

Create a set_env.sh in project root:

export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export REGION="us-central1"
export API_BASE_URL=$(gcloud run services describe way-back-home-api --format='value(status.url)')
export MAP_BASE_URL=$(gcloud run services describe way-back-home-frontend --format='value(status.url)')

🎓 Workshop Hosting Guide

Before the Workshop

1. Deploy backend and frontend to your GCP project. Ensure you pass your Cloud Run service URLs to the substitutions flag in gcloud builds submit.

2. Configure Admin Access: The API requires callers of admin endpoints to be registered in the admins Firestore collection.

   • Go to Firebase Console > Firestore.
   • Create a collection named admins.
   • Create a document where the Document ID is your email (e.g., [email protected]).
   • Add a field active: true (boolean).

3. Create an event using one of the following methods:

Method A: Firestore (Manual - Recommended for quick start)

Create a document in the events collection with the following structure:

• Collection: events
• Document ID: bwai-mycity (or your chosen event code)
• Fields:
  • active: true (boolean)
  • code: "bwai-mycity" (string)
  • created_at: [Current Timestamp] (timestamp)
  • created_by: "admin" (string)
  • description: "" (string)
  • max_participants: 500 (number)
  • name: "Build With IA - GDG SJC" (string)
  • participant_count: 0 (number)

Method B: CLI (Recommended for automated setup)

Use the provided Python script to create an event directly in Firestore using your authenticated gcloud credentials:

python3 scripts/create_event.py your-event-code "Your Workshop Name" --project YOUR_PROJECT_ID

Method C: API

1. Retrieve a Firebase ID Token from the terminal:

   # 1. Get your Google Identity Token
   ID_TOKEN=$(gcloud auth print-identity-token)
   
   # 2. Exchange it for a Firebase ID Token (requires Firebase Web API Key)
   # You can find your API Key in the Firebase Console > Project Settings
   API_KEY="YOUR_FIREBASE_WEB_API_KEY"
   
   curl -s -X POST "https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=${API_KEY}" \
     -H "Content-Type: application/json" \
     -d "{\"postBody\": \"id_token=${ID_TOKEN}&providerId=google.com\", \"requestUri\": \"http://localhost\", \"returnIdpCredential\": true, \"returnSecureToken\": true}" | jq -r .idToken
   

2. Call the Admin API:

   curl -X POST https://api.yourdomain.dev/admin/events \
     -H "Authorization: Bearer $FIREBASE_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"code": "your-event-code", "name": "Your Workshop Name"}'
   

3. Generate QR codes pointing to your event URL.

4. Test the full flow with a sample participant.

During the Workshop

1. Share the event code with participants
2. Direct them to the Level 0 Codelab
3. Monitor the live map at https://yourdomain.dev/e/your-event-code
4. Celebrate as beacons light up across the planet!

Cost Estimates

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Development Setup

# Backend
cd dashboard/backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8080

# Frontend
cd dashboard/frontend
npm install
npm run dev

📄 License

Apache 2.0 - See LICENSE for details.

🙏 Acknowledgments

• Built with Google ADK (Agent Development Kit)
• Powered by Vertex AI and Gemini
• 3D visualization with React Three Fiber

Ready to find your way back home? Start with Level 0 🚀