🏟️ CrowdCommand — AI-Powered Stadium Operations Assistant

A real-time intelligent dashboard that monitors crowd dynamics, predicts congestion, and enables operators to take immediate action through an AI-driven decision system.

---

🎯 Overview

CrowdCommand is a smart stadium operations platform designed to manage large-scale crowds efficiently during live events.

It transforms raw real-time data into actionable insights, helping operators:

• Detect congestion early
• Predict risk zones
• Execute corrective actions instantly

👉 Moving from reactive monitoring → predictive control

---

🏗️ Architecture

promptwar1/
├── client/                    # React + Vite frontend
│   ├── src/
│   │   ├── components/        # UI components (Heatmap, Gates, Queues, Alerts)
│   │   ├── hooks/             # Custom hooks (AI Decision Engine logic)
│   │   ├── services/          # WebSocket connection manager
│   │   ├── utils/             # Helper utilities
│   │   ├── App.jsx            # Main orchestrator
│   │   ├── main.jsx           # Entry point
│   │   ├── index.css          # Design system
│   │   └── intelligence.css   # AI + alert styling
│
├── server/                    # Node.js + Express backend
│   ├── models/                # Stadium configuration models
│   ├── routes/                # API endpoints (/api/health, /api/snapshot)
│   ├── services/              # Simulation + operator logic
│   ├── utils/                 # Validation + helpers
│   ├── tests/                 # Jest + supertest API tests + validation suite
│   ├── config.js              # Environment config
│   └── index.js               # Server entry point
│
├── Dockerfile                 # Multi-stage Docker build for Cloud Run
├── .dockerignore              # Docker build exclusions
└── .gitignore

---

⚙️ Core Features

🗺️ Live Crowd Heatmap

• 8-zone real-time density tracking
• Color-coded (Safe / Busy / Critical)
• Trend indicators + predictive capacity estimation

---

🚪 Smart Gate Monitoring

• 6 gates with wait time + throughput
• Automatically highlights fastest entry
• Helps redistribute crowd flow

---

⏳ Virtual Queue System

• Dynamic queues for 10 concession stands
• Real-time join/leave operations
• Live wait-time estimation

---

🧠 AI Decision Engine

• Rule-based intelligent system analyzing live data

• Generates prioritized recommendations:

• 🚨 Critical → Open emergency exit, reroute crowd

• ⚠️ Warning → Redirect to faster gate

• 📈 Info → Add service counter

---

🎛️ Operator Action System

• Interactive control panel
• Execute actions:
  • Redirect crowd
  • Open exits
  • Manage gates

👉 Actions trigger real-time feedback:

• Congestion reduces
• System updates instantly

---

🚨 Alert & Feedback System

• Auto-triggered alerts on critical thresholds
• Toast notifications for:
  • system warnings
  • successful actions

---

⚡ Performance & Real-Time Design

• WebSocket updates every 2 seconds
• Optimized React rendering:
  • useMemo — memoized computed values
  • useCallback — stable event handler references
  • React.memo — prevents unnecessary child re-renders
• gzip compression on all HTTP responses
• Efficient ring-buffer for action history

👉 Ensures smooth real-time UI even under heavy updates

---

🧪 Testing

Jest API Tests

cd server
npm install
npm test

Runs 34+ Jest tests across 4 test files with supertest covering:

• API Endpoints (app.test.js): Health (200, status, service, uptime, timestamp), Snapshot (zones, gates, queues, occupancy), 404 handling
• Validation (app.test.js): Queue actions (valid, missing, string, negative, null), Operator actions (valid, invalid targetType, empty, missing actionType)
• Simulation (app.test.js): Zone count, occupancy ranges, status values, gate count, fastest gate marking, queue lengths
• Actions Service (actions.test.js): Zone, gate, and queue actions including edge cases (unknown IDs, unknown action types, boundary clamping)
• Clamp Utility (clamp.test.js): Boundary, within-range, equal-min/max, negative ranges, and decimal values

Lightweight Validation Suite

cd server
npm run validate

Covers 24 assertions across:

• Clamp utility
• Input validation
• Queue logic
• Simulation data shapes
• Operator actions

---

🔐 Security

• Helmet — HTTP security headers (X-Frame-Options, X-Content-Type-Options, etc.)
• express-rate-limit — 100 requests per 15 minutes per IP on API routes
• Input validation — inline + utility-based on all WebSocket events
• CORS — configurable origin policy via environment variable
• Socket rate limiting — throttle on queue and operator actions
• Try/catch error handling — all socket handlers wrapped
• Global error handler — catches unhandled Express errors
• No hardcoded secrets — environment-based configuration (.env)
• Non-root Docker user — production container runs as appuser

---

Google Services Used

• Google Cloud Run (deployment)
• Gemini API (AI advisory generation)
• Antigravity (AI-assisted development)
• Google Stitch (UI generation)

---

☁️ Google Cloud Integration

Designed for deployment on Google Cloud Run:

• Uses process.env.PORT (defaults to 8080)
• Multi-stage Dockerfile with health check
• Stateless backend (cloud-native)
• /api/health endpoint for monitoring and readiness checks
• gzip compression for optimized bandwidth
• Scalable real-time WebSocket architecture

---

♿ Accessibility

• Semantic HTML5 elements (<header>, <main>, <section>, <aside>, <nav>)
• ARIA roles: banner, main, tablist, tab, dialog, alert, status, progressbar, list, listitem, region, log, application
• aria-label on all interactive elements (buttons, cards, panels)
• aria-live="polite" for dynamic content updates
• aria-hidden="true" on decorative icons
• Keyboard navigation: tabIndex, onKeyDown handlers
• Proper heading hierarchy (<h1>, <h2>)

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm 9+

Backend

cd server
npm install
npm run dev

Frontend

cd client
npm install
npm run dev

Running Tests

cd server
npm test

---

🚀 Deployment

Google Cloud Run

Option 1: Direct deploy

gcloud run deploy crowdcommand \
  --source . \
  --region asia-south1 \
  --allow-unauthenticated

Option 2: Docker build

docker build -t crowdcommand .
docker run -p 8080:8080 crowdcommand

Environment Variables

Variable	Default	Description
PORT	8080	Server port (Cloud Run injects this)
NODE_ENV	development	Environment mode
CORS_ORIGIN	*	Allowed CORS origins
BROADCAST_INTERVAL_MS	2000	WebSocket update frequency

---

📊 Impact

• Reduces waiting time
• Improves crowd flow
• Enhances operational safety
• Enables real-time decision making

---

🤖 AI Usage

This project was built using AI-assisted development with Google tools:

• Gemini (code refinement & logic design)
• Antigravity (agent-based development workflow)
• Google Stitch (UI generation)
• Google Cloud (deployment-ready architecture)

Structured prompting was used to simulate a multi-agent development process across frontend, backend, and system design.

---

🏁 Conclusion

CrowdCommand demonstrates how AI and real-time systems can transform stadium operations into intelligent, responsive environments.

---

📌 Submission Links

• GitHub Repo: https://github.com/aashitanegii/crowdcommand
• Live Demo: https://crowdcommand-866673965866.asia-south1.run.app/
• Blog/Article: https://medium.com/@last2braincellsdumps/crowdcommand-ai-powered-stadium-intelligence-43c778bf5cbc