🚀 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:

   gcloud builds submit --config cloudbuild.yaml \
     --substitutions=_API_BASE_URL=https://api.yourdomain.dev,_MAP_BASE_URL=https://yourdomain.dev
   

Environment Configuration

Create a set_env.sh in project root (generated by setup scripts):

export GOOGLE_CLOUD_PROJECT="your-project-id"
export REGION="us-central1"
export API_BASE_URL="https://api.yourdomain.dev"
export MAP_BASE_URL="https://yourdomain.dev"

🎓 Workshop Hosting Guide

Before the Workshop

1. Deploy backend and frontend to your GCP project
2. Create an event in the admin panel or via 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 🚀