🏆 Built for Hack2Skill Virtual PromptWars Challenge 4 — FIFA World Cup 2026 fan navigation assistant powered by Google Gemini.
StadiumGuide AI is an accessibility-first fan companion that generates personalized step-by-step route plans inside stadiums. It factors in accessibility needs, crowd conditions, urgency to kickoff, and real-time judge-uploaded crowd data to deliver the safest, fastest path to your seat.
🔗 Live Demo: stadiumguide.onrender.com
| Feature | Description |
|---|---|
| 🧠 AI-Powered Routing | Google Gemini (gemini-3.1-flash-lite) generates personalized routes with step-by-step directions, accessibility notes, and alternative paths. |
| ♿ Accessibility-First | Full support for wheelchair users, low vision, hearing impaired, sensory-sensitive fans, families with strollers, and elderly visitors. |
| 🌍 Multilingual | AI responses in the fan's preferred language — English, Hindi, Spanish, French, and more. |
| 🚨 Emergency Mode | One-tap access to the fastest safe exit, bypassing standard routing logic to prioritize safety and accessibility. |
| ⚡ Quick Actions | Instant AI-generated guidance for nearest restroom, food (halal/vegan options), and first aid. |
| 📊 Judge Upload | Real-time crowd data integration via JSON/CSV upload to dynamically re-route fans away from congested areas. |
| 🎨 Responsive Dark UI | Clean, dark-themed interface built with CSS Modules — no Tailwind, fully mobile-friendly. |
| ⌨️ Keyboard Accessible | Skip-to-content link, focus-visible states, aria-live regions, and full keyboard navigation. |
| 🛡️ Abuse Protection | Built-in rate limiting (10 requests / 15 min per IP) with Helmet (CSP, frame guard, no-sniff) and CORS origin allowlisting. |
| Layer | Technology |
|---|---|
| Frontend | React + Vite, CSS Modules (No Tailwind) |
| Backend | Node.js + Express |
| AI Engine | Google Gemini API (gemini-3.1-flash-lite) |
| Validation | express-validator for strict schema checks |
| Security | Helmet (CSP, frame guard, no-sniff), CORS origin allowlisting, rate limiting |
| Containerization | Docker + Nginx (multi-stage build) |
| Deployment | Render (currently live) + Google Cloud Run (Docker-ready) |
The live demo above runs on Render using the Node runtime — no Docker or Nginx layer. Express serves the built React frontend directly via express.static + an SPA fallback route.
| Setting | Value |
|---|---|
| Runtime | Node |
| Build Command | npm install && cd server && npm install && cd ../client && npm install && npm run build |
| Start Command | node server/index.js |
| Plan | Free |
Required Environment Variables:
| Key | Description |
|---|---|
GEMINI_API_KEY |
Your Google Gemini API key |
PRODUCTION_ORIGIN |
Your deployed URL (e.g. https://stadiumguide.onrender.com) — required for CORS to allow the frontend's own asset requests |
The repository also includes a multi-stage Dockerfile that builds the Vite frontend, packages the Node backend, and uses Nginx to serve static files and proxy /api/ requests to Node.
# Build the container
docker build -t stadiumguide .
# Test locally with Docker
docker run -p 8080:8080 -e GEMINI_API_KEY="your_api_key_here" stadiumguide
# Deploy to Google Cloud Run
gcloud run deploy stadiumguide \
--source . \
--port 8080 \
--allow-unauthenticated \
--set-secrets="GEMINI_API_KEY=your_secret_name:latest"Note: Cloud Run requires an active GCP billing account.
Shaurya Singh — Second-year B.Tech CSE (AI & ML)
🐙 GitHub: Shaurya2008-hub
MIT License — feel free to use, fork, and build upon this project.