# VenueFlow — Smart Sporting Venue Experience Platform A Flask-based real-time system that transforms the physical event experience at large-scale sporting venues by addressing crowd movement, waiting times, and real-time coordination. --- ## Problem Statement Attendees at large sporting events face: - **Crowd congestion** at gates, concourses, and exits - **Long queues** at food stalls, merchandise, and restrooms - **Poor wayfinding** inside massive, unfamiliar venues - **No real-time information** about crowd conditions or wait times - **Accessibility barriers** for attendees with disabilities VenueFlow solves these with an intelligent, real-time web platform for both **fans** (mobile-first attendee app) and **operators** (venue management dashboard). --- ## Architecture Overview ``` ┌──────────────────────────────────────────────────────────┐ │ FRONTEND (Jinja2 + JS) │ │ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Attendee│ │ Operator │ │ Heatmap │ │ Chatbot │ │ │ │ App │ │Dashboard │ │ View │ │ Widget │ │ │ └────┬────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ └─────────────┴────────────┴──────────────┘ │ │ │ SSE / Fetch │ ├──────────────────────────┼───────────────────────────────┤ │ FLASK BACKEND │ │ ┌──────────┐ ┌────────────┐ ┌──────────────┐ │ │ │ Auth & │ │ Real-time │ │ AI Engine │ │ │ │ Security │ │ Engine │ │ (Gemini) │ │ │ └──────────┘ └────────────┘ └──────────────┘ │ │ ┌──────────┐ ┌────────────┐ ┌──────────────┐ │ │ │ Queue │ │ Crowd │ │ Notification │ │ │ │ Manager │ │ Analytics │ │ Service │ │ │ └──────────┘ └────────────┘ └──────────────┘ │ ├──────────────────────────────────────────────────────────┤ │ GOOGLE SERVICES │ │ ┌──────────┐ ┌────────────┐ ┌──────────────┐ │ │ │ Firebase │ │Google Maps │ │ Gemini │ │ │ │ Firestore│ │ JS API │ │ 2.5 API │ │ │ └──────────┘ └────────────┘ └──────────────┘ │ │ ┌──────────┐ ┌────────────┐ │ │ │ Cloud │ │ Firebase │ │ │ │Translate │ │ Auth │ │ │ └──────────┘ └────────────┘ │ └──────────────────────────────────────────────────────────┘ ``` ### Tech Stack | Layer | Technology | |-------|-----------| | **Backend** | Python 3.11+, Flask, Flask-SocketIO | | **Frontend** | Jinja2 templates, Vanilla JS, CSS3 | | **Database** | Firebase Firestore (real-time sync) | | **Auth** | Firebase Authentication | | **Maps** | Google Maps JavaScript API | | **AI** | Google Gemini 2.5 Flash API | | **Translation** | Google Cloud Translation API | | **Real-time** | Server-Sent Events (SSE) + Firebase listeners | | **Deployment** | Docker-ready for Cloud Run | --- ## User Review Required > [!IMPORTANT] > **Google API Keys Required**: You will need to provide API keys / service accounts for: > - Firebase project (Firestore + Auth) > - Google Maps JavaScript API key > - Google Gemini API key > - Google Cloud Translation API key > > These will be stored in a `.env` file (never committed to git). > [!WARNING] > **Simulated Sensor Data**: Since we don't have physical IoT sensors, the system will include a **simulation engine** that generates realistic crowd density, queue lengths, and movement patterns. This makes the demo fully functional without hardware. > [!IMPORTANT] > **Two User Interfaces**: > 1. **Attendee App** (mobile-first) — For fans at the venue > 2. **Operator Dashboard** — For venue staff/management > > Both are served from the same Flask app. Please confirm this dual-interface approach. --- ## Proposed Changes ### Project Structure ``` EventManager/ ├── app.py # Flask application factory ├── config.py # Configuration & env management ├── requirements.txt # Python dependencies ├── Dockerfile # Container deployment ├── .env.example # Environment variable template ├── .gitignore │ ├── blueprints/ │ ├── __init__.py │ ├── auth.py # Authentication routes │ ├── attendee.py # Attendee-facing routes │ ├── operator.py # Operator dashboard routes │ ├── api.py # REST API endpoints │ └── sse.py # Server-Sent Events stream │ ├── services/ │ ├── __init__.py │ ├── firebase_service.py # Firebase Firestore & Auth │ ├── crowd_service.py # Crowd density analytics │ ├── queue_service.py # Queue management logic │ ├── gemini_service.py # AI chatbot & recommendations │ ├── maps_service.py # Maps & wayfinding │ ├── translation_service.py # Multi-language support │ ├── notification_service.py # Alert & notification engine │ └── simulator.py # Realistic data simulation │ ├── models/ │ ├── __init__.py │ ├── venue.py # Venue, Zone, Gate models │ ├── queue.py # Queue & wait time models │ └── event.py # Event & attendee models │ ├── static/ │ ├── css/ │ │ ├── base.css # Design system & tokens │ │ ├── attendee.css # Attendee app styles │ │ ├── operator.css # Operator dashboard styles │ │ └── accessibility.css # A11y overrides │ ├── js/ │ │ ├── app.js # Core JS utilities │ │ ├── heatmap.js # Crowd heatmap rendering │ │ ├── queue.js # Queue display & updates │ │ ├── wayfinding.js # Navigation & routing │ │ ├── chatbot.js # Gemini chatbot widget │ │ ├── notifications.js # Real-time notification handler │ │ ├── sse-client.js # SSE connection manager │ │ ├── dashboard.js # Operator dashboard logic │ │ ├── simulator-ui.js # Simulation controls │ │ └── accessibility.js # A11y toggle & preferences │ └── images/ │ └── (generated assets) │ ├── templates/ │ ├── base.html # Base template with a11y │ ├── attendee/ │ │ ├── home.html # Fan landing page │ │ ├── heatmap.html # Live crowd heatmap │ │ ├── queues.html # Queue status & booking │ │ ├── navigate.html # Wayfinding page │ │ └── profile.html # Preferences & a11y settings │ ├── operator/ │ │ ├── dashboard.html # Main control dashboard │ │ ├── analytics.html # Historical analytics │ │ ├── alerts.html # Alert management │ │ └── simulator.html # Simulation controls │ ├── auth/ │ │ ├── login.html │ │ └── register.html │ └── components/ │ ├── chatbot.html # Chatbot widget partial │ ├── notification.html # Notification toast partial │ └── nav.html # Navigation component │ └── tests/ ├── __init__.py ├── conftest.py # Pytest fixtures ├── test_auth.py # Authentication tests ├── test_crowd_service.py # Crowd analytics tests ├── test_queue_service.py # Queue management tests ├── test_api.py # API endpoint tests ├── test_simulator.py # Simulator logic tests └── test_accessibility.py # Accessibility audit tests ``` --- ### Component 1: Core Application & Configuration #### [NEW] `app.py` - Flask application factory pattern with blueprint registration - CORS, CSP, and security headers middleware - Error handlers (404, 500) with accessible error pages - SSE stream endpoint registration #### [NEW] `config.py` - Environment-based configuration (dev/staging/prod) - Secure loading of all API keys from `.env` - Firebase, Gemini, Maps, Translation config constants #### [NEW] `requirements.txt` Key dependencies: ``` flask>=3.1 flask-socketio>=5.3 firebase-admin>=6.5 google-generativeai>=0.8 google-cloud-translate>=3.16 gunicorn>=22.0 python-dotenv>=1.0 pytest>=8.0 ``` --- ### Component 2: Authentication (Firebase Auth) #### [NEW] `blueprints/auth.py` - Login / Register routes using Firebase Authentication - Role-based access: `attendee` vs `operator` - Session management with secure HTTP-only cookies - CSRF protection on all forms #### [NEW] `services/firebase_service.py` - Firebase Admin SDK initialization (singleton) - Firestore CRUD helpers with connection pooling - Real-time listener setup for zone/queue collections - Token verification for authenticated API calls --- ### Component 3: Real-Time Crowd Heatmap #### [NEW] `services/crowd_service.py` - Processes zone density data from Firestore - Calculates crowd density levels: 🟢 Low / 🟡 Moderate / 🔴 High / ⚫ Critical - Threshold-based alerting triggers - Historical trend computation #### [NEW] `static/js/heatmap.js` - Renders interactive venue map overlay using **Google Maps JavaScript API** - Real-time heatmap layer with color-coded zones - Click-to-inspect zone details (capacity, current count, trend) - Auto-refresh via SSE stream #### [NEW] `templates/attendee/heatmap.html` - Mobile-first responsive layout - Legend with WCAG-compliant color indicators + text labels - "Best route" suggestion panel - Accessible alternative: tabular zone status view --- ### Component 4: Queue Management System #### [NEW] `services/queue_service.py` - Manages virtual queues for food, merchandise, restrooms - Estimated wait time calculation (moving average algorithm) - "Book your spot" — virtual queue reservation - Queue position tracking and SMS/notification alerts #### [NEW] `static/js/queue.js` - Live queue dashboard with animated progress bars - Sort/filter by wait time, category, proximity - "Join Queue" button with confirmation modal - Real-time position counter #### [NEW] `templates/attendee/queues.html` - Card-based queue listings with status indicators - Category filters (🍕 Food, 🛍 Merch, 🚻 Restrooms) - Estimated wait time with confidence indicator - Virtual queue ticket with QR code --- ### Component 5: Wayfinding & Navigation #### [NEW] `services/maps_service.py` - Google Maps integration for venue layout - Shortest-path routing between venue zones - Accessibility-aware routing (elevators, ramps) - Points-of-interest data management #### [NEW] `static/js/wayfinding.js` - Interactive venue map with Google Maps JS API - Turn-by-turn directions within the venue - "Navigate to nearest [restroom/food/exit]" functionality - Crowd-aware routing (avoids congested paths) #### [NEW] `templates/attendee/navigate.html` - Full-screen map with controls - Quick-action buttons: "Nearest Exit", "My Seat", "Food Court" - Step-by-step accessible text directions - Estimated walking time display --- ### Component 6: AI Chatbot (Google Gemini) #### [NEW] `services/gemini_service.py` - Gemini 2.5 Flash integration for conversational AI - Context-aware: knows venue layout, current crowd data, queue times - Multi-language support via Cloud Translation API - Safety filters and responsible AI guardrails - Prompts: - "Where's the shortest food queue?" - "How do I get to Gate 7?" - "Is Section B crowded right now?" #### [NEW] `static/js/chatbot.js` - Floating chat widget (bottom-right) - Message bubbles with typing indicator - Quick-reply suggestion chips - Language selector for real-time translation - ARIA live region for screen reader announcements #### [NEW] `templates/components/chatbot.html` - Accessible chat interface with proper ARIA roles - Resizable/minimizable widget - Keyboard-navigable message list --- ### Component 7: Operator Dashboard #### [NEW] `blueprints/operator.py` - Protected routes (operator role required) - Dashboard, analytics, alerts, and simulator views - API endpoints for crowd threshold management #### [NEW] `static/js/dashboard.js` - Real-time KPI cards (total attendance, avg wait, alerts) - Zone-by-zone capacity meters - Alert timeline with severity levels - Staff deployment recommendations #### [NEW] `templates/operator/dashboard.html` - Grid layout with responsive breakpoints - Live charts (crowd trends, queue throughput) - Draggable alert cards - Emergency broadcast panel --- ### Component 8: Notification & Alert System #### [NEW] `services/notification_service.py` - Multi-channel: in-app toasts, SSE push, email - Priority levels: Info / Warning / Critical / Emergency - Geo-targeted: alerts to specific venue zones - Automatic triggers from crowd density thresholds #### [NEW] `blueprints/sse.py` - Server-Sent Events endpoint for real-time push - Per-user event filtering (zone, role) - Heartbeat keep-alive for connection stability - Graceful reconnection handling #### [NEW] `static/js/notifications.js` - Toast notification stack (top-right) - Sound alerts for critical notifications - Notification center with history - "Do Not Disturb" mode for operators --- ### Component 9: Simulation Engine #### [NEW] `services/simulator.py` - Generates realistic crowd movement patterns - Simulates event lifecycle: pre-event → kickoff → halftime → post-event - Queue fluctuation with realistic distributions - Configurable parameters: venue capacity, event type, weather - Writes simulated data to Firestore in real-time #### [NEW] `templates/operator/simulator.html` - Simulation control panel (start/stop/speed) - Event phase selector - Parameter sliders (crowd size, arrival rate) - Live preview of simulated data --- ### Component 10: Accessibility & Internationalization #### [NEW] `static/css/accessibility.css` - High-contrast mode styles - Large text mode (150% scaling) - Reduced motion preference support - Focus indicator styles (3px solid, 3:1 contrast) #### [NEW] `static/js/accessibility.js` - Accessibility preferences panel - Toggle: high contrast, large text, reduced motion - Persisted via localStorage - Screen reader announcement utility #### [NEW] `services/translation_service.py` - Google Cloud Translation API integration - Auto-detect user language from browser - On-demand translation of UI strings and notifications - Cached translations for performance --- ## Google Services Integration Summary | Google Service | Usage | Why | |---|---|---| | **Firebase Firestore** | Real-time database for crowd, queue, and event data | Sub-second sync, offline support, scales automatically | | **Firebase Auth** | User authentication (email/social login) | Secure, supports role-based access, easy integration | | **Google Maps JS API** | Venue map, heatmap overlay, wayfinding routes | Industry standard mapping, custom overlays, directions | | **Gemini 2.5 Flash** | AI chatbot for attendee assistance | Context-aware responses, fast inference, multi-turn | | **Cloud Translation** | Multi-language support | Real-time translation for international events | --- ## Security Implementation 1. **Authentication**: Firebase Auth with JWT token verification 2. **Authorization**: Role-based access control (attendee/operator/admin) 3. **CSRF**: Flask-WTF CSRF tokens on all forms 4. **CSP**: Content Security Policy headers 5. **Input Validation**: Server-side validation on all endpoints 6. **Rate Limiting**: API rate limiting to prevent abuse 7. **Secrets Management**: All keys in `.env`, never in source 8. **HTTPS**: Enforced in production via Dockerfile/Cloud Run 9. **XSS Protection**: Jinja2 auto-escaping enabled 10. **SQL Injection**: N/A (NoSQL Firestore) — Firestore Security Rules used --- ## Accessibility Compliance (WCAG 2.2 AA) - **Contrast**: All text ≥ 4.5:1 ratio, UI components ≥ 3:1 - **Target Size**: All interactive elements ≥ 44×44 CSS pixels - **Keyboard Navigation**: Full keyboard support with visible focus indicators - **Screen Readers**: ARIA landmarks, live regions, proper heading hierarchy - **Reduced Motion**: `prefers-reduced-motion` media query support - **High Contrast Mode**: Toggle-able high contrast theme - **Skip Links**: "Skip to content" link on every page - **Semantic HTML**: Proper use of `