SmartVenue AI 🏟️🤖

SmartVenue AI is an end-to-end project designed to revolutionize the attendee experience at large-scale sporting venues. It uses real-time data, explainable AI recommendations, and Google Cloud technologies to optimize crowd flow, safety, and operational efficiency.

---

Vision

Attendees at stadiums should not spend most of their time in queues, and organizers should not struggle to see the “big picture” of what is happening across the venue.

SmartVenue AI bridges this gap with an intelligent layer that:

• Guides fans to better gates, routes, and facilities.
• Gives operators a live pulse of crowd congestion, wait times, and alerts.

---

Chosen Vertical

Physical Event Experience for attendees at large-scale sporting venues.

SmartVenue AI is built for stadiums and sports arenas where:

• Crowd congestion and long queues are common.
• Attendees struggle with navigation and facility discovery.
• Organizers need real-time situational awareness and coordination.

---

Core Features

• 📱 Attendee Experience

  • Mobile-first dashboard tailored for stadium visitors.
  • Gate recommendations with estimated crowd load and waiting time.
  • Real-time alerts for congestion, safety, or special announcements.

• 🤖 AI Assistant

  • Conversational helper for attendees.
  • Answers questions like “Which gate should I use?”, “Where is the nearest washroom?”, or “How long is the queue at Food Court B?”.

• 📊 Admin Dashboard

  • “Pulse” view summarizing venue health at a glance.
  • Live congestion metrics per zone/gate.
  • Tools for dispatching alerts and updating venue state.

• ⚡ Real-time Sync

  • Built on Firestore for real-time updates across attendee and admin views.

• 🧠 Explainable AI

  • Recommendations come with reasons, e.g.
    “Use Gate 3: currently 40% lower load compared to Gate 1 and closer to your seat.”

---

Tech Stack

Frontend

• React
• Vite
• Tailwind CSS (v4)
• Framer Motion
• Lucide Icons

Backend

• Node.js
• Express

Data & Auth

• Firebase Firestore
• Firebase Authentication

AI

• Google Gemini API (with deterministic heuristic fallback for demos)

Deployment

• Docker
• Google Cloud Run (frontend + backend services)

---

Approach and Logic

1. Venue Modeling

   • The stadium is divided into zones, gates, facilities (washrooms, food courts, merch), and paths.
   • Each entity has attributes such as live load, queue time, and status.

2. Live Data Layer

   • Admins or automated systems update crowd and queue metrics.
   • Firestore stores live state so both dashboards stay in sync.

3. Recommendation Engine

   • Combines:
     • Current crowd density and queue times.
     • User’s current or preferred zone.
     • Distance or relative convenience.
   • Produces recommendations such as:
     • Best gate to enter.
     • Best facility to use (shortest queue).
     • Safer or less crowded route.

4. Explainable AI Layer

   • Gemini is used (or heuristics fallback) to turn raw metrics into clear natural language explanations.
   • Example: “We recommend Food Court East because its waiting time is 5 minutes vs 17 minutes at Food Court North.”

5. Experience Design

   • Attendee dashboard focuses on clarity and one-tap actions.
   • Admin dashboard focuses on high-level overview plus quick controls.

---

How the Solution Works

1. Admin Flow

   • Admin logs in and updates:
     • Crowd levels per gate/zone.
     • Queue times for facilities.
     • Any alerts (e.g., congestion, incident, rerouting).
   • Data is written to Firestore.

2. Data Sync

   • Firestore broadcasts changes in real time.
   • Both dashboards subscribe to the same data, so updates appear instantly.

3. Attendee Flow

   • Attendee opens the SmartVenue AI interface (mobile-first).
   • Selects their gate/zone or target area.
   • Sees recommended gate, facility, and path with an explanation.
   • Can ask the AI assistant a question to refine guidance.

4. AI Behavior

   • If Gemini API key is configured:
     • Backend calls Gemini for natural-language explanation and richer reasoning.
   • If Gemini is not available:
     • Backend uses deterministic heuristic text generation for consistent, demo-ready responses.

5. Resilience for Demo

   • If Firestore is not available in a local/demo setup:
     • Backend falls back to an internal mock state that simulates live data.

---

Project Structure

smartvenue-ai-platform/
  frontend/        # React + Vite application (attendee + admin UI)
  backend/         # Express API server + AI/recommendation logic
  shared/          # Shared constants, types, and helper functions
  docs/            # Architecture, API reference, design notes
  docker-compose.yml
  README.md

Key docs:

• Architecture
• API Reference

---

Getting Started

Prerequisites

• Node.js (v20+ recommended)
• Docker & Docker Compose
• A Firebase project (optional but recommended)
• Google Gemini API key (optional but recommended)

Clone the Repository

git clone https://github.com/NaniToka/smartvenue-ai-platform.git
cd smartvenue-ai-platform

Make sure the repository is cloned into your chosen environment (e.g., Google Antigravity for PromptWars development, or your local machine).

Install Dependencies

From the project root:

npm run install:all

This installs dependencies for both frontend and backend.

Environment Setup

Create a .env file in the project root (or in the backend folder if you prefer separation):

GEMINI_API_KEY=your_key_here
FIREBASE_SERVICE_ACCOUNT={"project_id": "...", "client_email": "...", "private_key": "..."}

• If GEMINI_API_KEY is not set, the backend will use deterministic heuristic responses.
• If FIREBASE_SERVICE_ACCOUNT is not set, the backend falls back to internal mock data for a “ready to demo” experience.

Run in Development

In one terminal:

npm run dev:backend

In another terminal:

npm run dev:frontend

• Frontend: http://localhost:5173
• Backend: http://localhost:5001

---

Docker & Local Container Deployment

To run the whole stack using Docker Compose:

docker-compose up --build

After build completes:

• The app will be available at: http://localhost:3000

This mimics the production-style container deployment that also runs on Google Cloud Run.

---

Cloud Deployment (Google Cloud Run)

SmartVenue AI is designed to deploy as two Cloud Run services:

• Backend Service

  • Dockerized Express API.
  • Deployed with gcloud run deploy smartvenue-backend ....

• Frontend Service

  • Dockerized Vite build served via a static server (e.g., nginx).
  • Deployed with gcloud run deploy smartvenue-frontend ....

Both services are set to --allow-unauthenticated for public hackathon access.

---

Assumptions

• Stadium/venue provides structured data about:
  • Zones, gates, facilities, and routes.
  • Current crowd levels and queue times.
• Attendees have mobile internet access during the event.
• Organizers can operate an admin dashboard to push live updates and alerts.
• Safety and security teams still make the final calls; SmartVenue AI acts as decision support, not a hard authority.
• In constrained environments (no Gemini or Firestore), simulated data and heuristic responses are acceptable for demonstrating logic and UX.

---

AI & Mock Fallbacks

This project is designed to be demo-ready, even without external keys:

• Gemini Fallback

  • If GEMINI_API_KEY is missing, the backend uses deterministic, rule-based text generators that produce stable explanations.

• Firestore Fallback

  • If Firestore is not configured for local demo:
    • Backend maintains an in-memory state that simulates venue conditions.

This ensures the judge can see a working experience without needing external configuration.

---

Testing & Quality

• Core logic functions are organized in the shared layer to encourage:
  • Unit testing of recommendation logic.
  • Easier refactoring and maintenance.
• The frontend uses:
  • Strong typing via TypeScript.
  • Clear separation of components, hooks, and UI sections.
• Accessibility considerations:
  • Mobile-first layout.
  • High-contrast colors and large touch targets where applicable.
  • Semantic HTML and ARIA where relevant.

---

Security & Efficiency

• API routes are designed to avoid exposing secrets or raw service accounts to the client.
• Environment variables are used for sensitive configuration.
• Containerized deployment on Cloud Run enables:
  • Automatic scaling down when not in use.
  • Pay-per-use efficiency.

---

Built For

This project was built for the Google Cloud PromptWars / Hack2Skill challenge, under the Physical Event Experience vertical, focusing on:

• Smart, dynamic assistant behavior.
• Logical decision making based on user context.
• Practical and real-world usability for stadium events.
• Meaningful integration of Google services (Cloud Run, Gemini, optionally Firestore/Firebase).

---

Google Services Used

• Google Cloud Run – hosts both frontend and backend as containerized services.
• Google Gemini API – powers explainable AI summaries and recommendations when configured.
• Firebase / Firestore – supports real-time venue state and synchronization in the demo architecture.