Intent-Aware CrowdFlow

A predictive navigation system for stadium crowds, helping users avoid congestion before it happens.

---

Context

This project was developed as part of the Virtual Prompt Wars: Build with AI, organized by Google for Developers in collaboration with Hack2Skill.

---

Problem Statement

Large sporting and event venues often experience severe congestion at critical points such as food stalls, restrooms, and exits.

Most existing systems are reactive—they respond only after congestion has already formed. This results in inefficient movement, long queues, and a poor attendee experience.

---

Solution Overview

Intent-Aware CrowdFlow introduces a predictive approach to crowd management.

Instead of reacting to congestion, the system:

• forecasts crowd distribution based on event phases
• enables intent-based navigation
• guides users through less congested paths proactively

This allows attendees to make better movement decisions before congestion builds up.

---

Key Features

• Predictive Crowd Density Switch between live and forecasted crowd states to anticipate congestion

• Intent-Aware Routing Navigate efficiently based on goals such as Food, Exit, or Restroom

• Graph-Based Pathfinding Uses Dijkstra’s algorithm to compute least-congested routes

• Node-Based Route Visualization Stepwise routing across a spatial hex grid for realistic navigation

• AI Recommendation Panel Provides contextual guidance based on predicted conditions

• Minimal, Focused Interface Designed for clarity, fast decision-making, and usability

---

What Makes This Different

Most systems answer:

“Where is the crowd right now?”

This system answers:

“Where will the crowd be next?”

By combining simulation, prediction, and routing, it enables:

• future-aware navigation
• proactive crowd distribution
• better real-time decision-making

---

How It Works (Simplified)

• The system simulates current crowd density across zones
• It predicts how crowds will shift in the next few minutes
• Based on user intent (e.g., food or exit), it computes the least congested path
• The route is visualized and updated dynamically

---

Tech Stack

• Frontend: React, Tailwind CSS, Framer Motion
• Backend: Flask (Python)
• Algorithms: Graph-based routing (Dijkstra)
• Infrastructure: Docker, Google Cloud Run
• Observability: Google Cloud Logging

---

Google Cloud Integration

The application leverages multiple Google Cloud services for scalability, observability, and data persistence:

• Cloud Run: Serverless deployment with automatic scaling and zero-downtime updates
• Cloud Logging: Structured logging for all API requests, routing computations, and system events
• Cloud Firestore: NoSQL database for analytics and route history tracking
• Container Registry: Secure Docker image storage and management
• Health Checks: Built-in /health endpoint for Cloud Run monitoring and auto-healing

Analytics & Monitoring:

• Route computations logged to Firestore for analytics
• Real-time logging via Cloud Logging
• Performance metrics tracked automatically
• Error tracking and alerting enabled

---

Security Features

• Rate Limiting: Request throttling (30 req/min per IP) to prevent abuse
• Input Validation: Pydantic schemas for all API inputs
• Security Headers: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, HSTS
• Error Handling: Comprehensive error handling with proper HTTP status codes
• CORS Configuration: Restricted cross-origin resource sharing

---

Accessibility

The application includes accessibility features to ensure usability for all users:

• Keyboard Navigation: All zones are keyboard-accessible with Enter/Space key support
• ARIA Labels: Semantic roles and descriptive labels for screen readers
• Grid Structure: Proper semantic HTML with grid roles for assistive technology
• Color Contrast: High contrast colors for visual clarity
• Responsive Design: Fully responsive layout across devices
• Error Messages: Clear, accessible error feedback

---

Code Quality & Best Practices

• Type Safety: Pydantic schemas for all API inputs
• Error Handling: Comprehensive try-catch blocks with proper logging
• Input Validation: All endpoints validate request data
• Logging: Structured logging at all critical points
• Testing: 25+ test cases covering all features
• Documentation: Inline comments and docstrings
• Modularity: Separation of concerns (simulation, prediction, routing)
• Performance: Optimized algorithms and efficient state management

---

Architecture

Frontend (React)
        │
        ▼
Flask API
        │
        ├── Simulation Engine
        ├── Prediction Engine
        └── Routing Engine

The system follows a modular architecture:

• Simulation Engine maintains real-time state
• Prediction Engine forecasts future density
• Routing Engine computes optimal paths

---

User Flow

1. User selects an intent (Food, Exit, Restroom)
2. System predicts near-future crowd distribution
3. Optimal route is computed using predicted density
4. Route is visualized across the map
5. AI panel provides actionable guidance

---

Running Locally

Backend

cd backend
pip install -r requirements.txt
python api.py

Frontend

cd frontend
npm install
npm run dev

Testing

cd backend
pytest test_logic.py -v --cov=. --cov-report=html

Test Coverage:

• Simulation engine (initialization, density updates, phase changes)
• Prediction logic (all event phases)
• Routing engine (multiple intents, edge cases)
• API endpoints (all 7 endpoints)
• Security headers validation
• Rate limiting verification
• Integration workflows
• Error handling

Total Tests: 25+ comprehensive test cases

---

API Endpoints

Endpoint	Method	Purpose
/api/density	GET	Get current crowd density
/api/prediction	GET	Get predicted crowd density
/api/route	POST	Compute optimal route
/api/wait-times	GET	Get wait times for facilities
/api/ai-recommendation	POST	Get AI guidance
/api/event-phase	POST	Set event phase
/health	GET	Health check

---

Docker / Deployment

docker build -t crowdflow .
docker run -p 8080:8080 -e PORT=8080 crowdflow

---

Screenshot of MVP

---

Summary

Intent-Aware CrowdFlow demonstrates how predictive systems can improve real-world navigation in crowded environments by shifting from reactive monitoring to proactive guidance.