CrowdControl is a real-time AI-powered stadium management and fan experience platform built for large-scale sporting venues. It combines live crowd intelligence, Gemini-powered navigation, predictive queue modelling, and personalised fan recommendations, all accessible from a single mobile-first web app.
The Problem: Attending a major sporting event often means navigating packed corridors, waiting in long queues, missing out on deals, and struggling to find your way around an unfamiliar venue.
The Solution: CrowdControl gives every fan a real-time AI co-pilot and gives venue staff a live operational command centre, turning chaos into a seamlessly guided experience.
- Interactive SVG stadium heatmap with 12 live zones (Sections A–L)
- Real-time colour-coded density: Optimal (green) → Active (yellow) → High (orange) → Critical (red)
- WebSocket-powered updates every 3 seconds with zero page refresh
- Pulsing zone animations for rapidly filling sections
- Hover tooltips: zone name, current headcount, capacity, and density trend
- One-click spatial report generation for venue operations staff
- Gemini 3-powered turn-by-turn routing across the entire venue
- Ingests live crowd density data to recommend the least congested path
- Destinations: Gates, Food Courts, Restrooms, Medical Bay, Merchandise, Exits
- Congestion warning badges when a route passes through high-density zones
- "Avoid Crowds" toggle that triggers an alternate AI-generated route
- Estimated walk time per route
- Tracks 8 service points: 3 food courts, 2 merchandise stores, 2 restroom clusters, 1 medical bay
- Wait time prediction powered by the M/M/1 queuing theory model (operations research)
- Real-time sparkline charts showing 10-minute wait history per service point
- "Best Choice" badge highlighting the shortest queue per category
- Filterable tabs: All | Food | Merch | Restrooms
- WebSocket live updates every 5 seconds
- 3-question onboarding: dietary needs, interests, time available
- Gemini 3 generates 5 hyper-personalised recommendations per fan
- Context-aware: accounts for live queue times, crowd density, active offers, and event stage
- Urgency labels: "Act Now", "Good Time", "Anytime"
- Swipeable recommendation cards with Framer Motion animations
- "Pulse It Again" for refreshed suggestions as the event evolves
- Live zone density data table across all 12 sections
- Queue length overview for all 8 service points
- Automated alert feed: zones exceeding 85% capacity trigger deployment recommendations
- Manual zone override: staff can mark zones as "Closed" to reroute navigation AI
https://crowd-frontend-987426744408.us-central1.run.app
https://www.loom.com/share/9e90eba7bc3d43e999925f2919f6aa39
| Module | URL |
|---|---|
| 🏠 Home | / |
| 🔴 CrowdLens | /map |
| ⏱️ QueueSense | /queue |
| ⚡ FanPulse | /recommendations |
| 🛡️ Admin Portal | /admin |
CrowdControl
├── Frontend (Next.js 14 + TypeScript + Tailwind CSS)
│ ├── /app/page.tsx → Fan Home + Venue Status Banner
│ ├── /app/map/page.tsx → CrowdLens Heatmap
│ ├── /app/queue/page.tsx → QueueSense Dashboard
│ ├── /app/recommendations/ → FanPulse AI Cards
│ ├── /app/admin/page.tsx → Staff Portal
│ └── /components/NavigationPanel.tsx → PathFinder Panel
│
├── Backend (Python FastAPI)
│ ├── /api/routes/crowd.py → Crowd density REST + WebSocket
│ ├── /api/routes/navigation.py → AI navigation routes
│ ├── /api/routes/queue.py → Queue prediction REST + WebSocket
│ ├── /api/routes/recommendations.py → FanPulse AI endpoint
│ ├── /services/gemini_service.py → Gemini 3 integration
│ ├── /services/crowd_service.py → Real-time zone simulation
│ ├── /services/queue_service.py → M/M/1 queue model
│ └── /services/recommendation_service.py → AI context builder
│
└── Infrastructure (Google Cloud Platform)
├── Cloud Run → Frontend + Backend containers
├── Artifact Registry → Docker image storage
├── Cloud Build → CI/CD pipeline
├── Firestore → Fan profiles + recommendation history
├── Firebase RTDB → Real-time event streaming
├── Pub/Sub → Crowd event messaging
└── Secret Manager → API key management
| Layer | Technology |
|---|---|
| Frontend | Next.js 14, TypeScript, Tailwind CSS, Framer Motion, Recharts |
| Backend | Python 3.11, FastAPI, WebSockets, Pydantic |
| AI / ML | Google Gemini 3 Pro (via google-generativeai SDK) |
| Realtime | WebSocket (FastAPI), Firebase Realtime Database |
| Database | Cloud Firestore |
| Deployment | Google Cloud Run |
| CI/CD | Google Cloud Build |
| Containers | Docker, Docker Compose |
| IDE / Agent | Google Antigravity (Gemini 3 agent-first IDE) |
- Python 3.11+
- Node.js 18+
- Google Cloud SDK
- A Gemini API key from aistudio.google.com
- A Firebase project
git clone https://github.com/kavinithi-sera/crowdcontrol.git
cd crowdcontrolcp .env.example .envEdit .env and fill in your values:
GEMINI_API_KEY=your_gemini_api_key
GCP_PROJECT_ID=your_gcp_project_id
FIREBASE_PROJECT_ID=your_firebase_project_id
NEXT_PUBLIC_API_URL=http://localhost:8000
GOOGLE_APPLICATION_CREDENTIALS=service-account-key.json
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000cd frontend
npm install
npm run devVisit http://localhost:3000 in your browser.
docker-compose up --buildThis starts both the frontend (port 3000) and backend (port 8000) together.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
firestore.googleapis.com \
pubsub.googleapis.com \
secretmanager.googleapis.com# Backend
gcloud builds submit --tag \
asia-southeast1-docker.pkg.dev/$PROJECT_ID/crowdcontrol-repo/backend ./backend
gcloud run deploy crowdcontrol-backend \
--image asia-southeast1-docker.pkg.dev/$PROJECT_ID/crowdcontrol-repo/backend \
--platform managed --region asia-southeast1 --allow-unauthenticated
# Frontend
gcloud run deploy crowdcontrol-frontend \
--image asia-southeast1-docker.pkg.dev/$PROJECT_ID/crowdcontrol-repo/frontend \
--platform managed --region asia-southeast1 --allow-unauthenticatedCI/CD is configured via cloudbuild.yaml — every push to main automatically builds and deploys.
crowdcontrol/
├── backend/
│ ├── app/
│ │ ├── main.py
│ │ ├── api/routes/
│ │ ├── services/
│ │ ├── models/
│ │ └── core/
│ ├── requirements.txt
│ └── Dockerfile
├── frontend/
│ ├── app/
│ ├── components/
│ ├── lib/
│ └── Dockerfile
├── .github/workflows/deploy.yml
├── docker-compose.yml
├── cloudbuild.yaml
├── .env.example
└── README.md
CrowdControl uses Google Gemini 3 Pro in three distinct ways:
-
PathFinder Navigation — Gemini receives a structured prompt containing the fan's current zone, destination, and a full snapshot of live crowd density across all 12 zones. It returns a JSON-structured step-by-step route that actively avoids congested areas.
-
FanPulse Recommendations — Gemini receives the fan's dietary preferences, interests, available time, current event stage (pre-game / halftime / post-game), live queue wait times, and active venue promotions. It generates 5 contextually relevant, urgency-labelled recommendations tailored specifically to that fan at that moment.
-
Venue Assistant Chatbot — A floating AI assistant on the home screen lets fans ask natural language questions. Gemini's system prompt is dynamically injected with live crowd and queue context so answers are always current and venue-aware.
QueueSense uses the M/M/1 queuing model from operations research to predict wait times:
Wait Time = Queue Length / (Service Rate - Arrival Rate)
This is the same mathematical model used in telecommunications, hospital management, and airport operations — applied here in real time to stadium service points, giving fans accurate, science-backed wait predictions rather than guesswork.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Built using Google Antigravity — the agent-first IDE developed by Google.