| # 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 `<nav>`, `<main>`, `<aside>`, `<section>` |
| - **Alt Text**: All images have descriptive alt text |
| - **Language**: `lang` attribute on `<html>`, translated content marked |
| |
| --- |
| |
| ## Testing Strategy |
| |
| ### Unit Tests (pytest) |
| ``` |
| tests/ |
| ├── test_crowd_service.py # Density calculation, threshold logic |
| ├── test_queue_service.py # Wait time estimation, virtual queue |
| ├── test_auth.py # Login, registration, role checks |
| ├── test_api.py # API endpoint responses |
| └── test_simulator.py # Simulation output validation |
| ``` |
| |
| ### Integration Tests |
| - Firebase Firestore read/write operations |
| - Gemini API response processing |
| - SSE event delivery end-to-end |
| |
| ### Accessibility Tests |
| - Automated: axe-core audit via browser subagent |
| - Manual: keyboard navigation flow verification |
| - Contrast ratio verification on all pages |
| |
| ### Browser Testing |
| - Mobile viewport (375px) responsive validation |
| - Desktop viewport (1440px) dashboard verification |
| - Cross-browser visual spot checks |
| |
| --- |
| |
| ## Verification Plan |
| |
| ### Automated Tests |
| 1. `pytest tests/ -v` — Run full test suite |
| 2. `flask run` — Verify app starts without errors |
| 3. Browser subagent: Navigate all pages, verify rendering |
| 4. Accessibility audit via axe-core integration |
| |
| ### Manual Verification |
| 1. Start simulation → observe real-time heatmap updates |
| 2. Join virtual queue → verify position tracking |
| 3. Ask chatbot questions → verify Gemini responses |
| 4. Toggle accessibility modes → verify contrast/text changes |
| 5. Switch languages → verify translation |
| |
| --- |
| |
| ## Execution Phases |
| |
| ### Phase 1: Foundation (Core + Auth + Database) |
| - `app.py`, `config.py`, `requirements.txt` |
| - Firebase service, Auth blueprints |
| - Base templates with design system |
| - Docker setup |
| |
| ### Phase 2: Real-Time Core (Heatmap + Queues + SSE) |
| - Crowd service + heatmap visualization |
| - Queue management system |
| - SSE real-time push infrastructure |
| - Simulation engine |
| |
| ### Phase 3: Intelligence (AI + Navigation + Notifications) |
| - Gemini chatbot integration |
| - Google Maps wayfinding |
| - Notification/alert system |
| - Cloud Translation integration |
| |
| ### Phase 4: Operations (Dashboard + Analytics) |
| - Operator dashboard with live KPIs |
| - Historical analytics views |
| - Alert management interface |
| - Simulation control panel |
| |
| ### Phase 5: Polish (A11y + Testing + Security) |
| - Accessibility features & compliance |
| - Comprehensive test suite |
| - Security hardening |
| - Performance optimization |
| - Final UI polish |
| |
| --- |
| |
| ## Open Questions |
| |
| > [!IMPORTANT] |
| > 1. **Do you have Google Cloud / Firebase API keys ready?** If not, I can set up the project with mock services that can be swapped for real ones later. |
| |
| > [!IMPORTANT] |
| > 2. **Venue type preference?** Should the demo simulate a specific type of venue (cricket stadium, football stadium, Olympic arena)? This affects the venue map layout. |
| |
| > [!NOTE] |
| > 3. **Should we include a mobile app wrapper** or keep this strictly as a responsive web app? (I recommend responsive web — works on all devices without installation.) |
| |
