FanConnect — AI-Powered World Cup Fan Concierge
FanConnect is an AI-powered fan concierge platform for the 2026 FIFA World Cup, helping 5.4M fans across 16 cities in the US, Canada, and Mexico find the best venues to watch games, check in with fellow fans, and plan their match nights.
Built for the Google Cloud Rapid Agent Hackathon (MongoDB Partner Track) — June 2026.
What It Does
- AI-Powered Venue Discovery — Real-time map of sports bars with crowd density heatmaps, team check-in reactions, and 5-sport filtering. Users can right-click anywhere on the map to create new venues, with automated deduplication (50m proximity + Levenshtein name matching) and rate limiting (5/hour per user) protecting data quality.
- Fan Check-ins & Reactions — Telegram-style reaction bar: fans check in with their team (200m proximity verified, 4-hour TTL), see live team distribution at each venue, and cancel anytime.
- City Leaderboard — Competitive venue rankings by real fan check-ins, gamifying the match-day experience
- AI Plan My Night — Gemini 2.5 Pro generates personalized 3-stop venue itineraries using real-time check-in data, live match schedules, and active promotions
- AI Chat Concierge — Natural language chat for venue recommendations, match schedules, and fan meetups
- Venue Business Platform — Venues can post events, create targeted promotions, and get AI-powered audience insights
- World Cup Match Schedule — Complete 104-match schedule with stadium map overlays, today-highlighting, and city filtering
- User Profile & Stats — Check-in history, venue stats (total check-ins, venues visited, top team), saved venues
Agent Autonomy Narrative
The Autonomous AI Concierge for World Cup Fans
FanConnect is not a search box — it's an autonomous AI agent that proactively orchestrates a fan's entire match-day experience. The agent operates across three layers of autonomy:
Layer 1 — Proactive Sensing (Real-Time World Model)
The agent continuously ingests and synthesizes live data streams without user prompting:
- Live Crowd Density: Every 30 seconds, the system aggregates check-in data across all venues in a city. The map overlay updates autonomously — showing fans where the action is in real time, from "Quiet" to "Overflow" levels.
- Match-Aware Context: The agent knows the full 104-match World Cup schedule. Stadium overlays highlight nearby venues, and "TODAY" badges surface on match day. When a user opens the app during Argentina vs Brazil, the agent pre-loads Argentina-friendly venues.
- Venue Reaction Bar: Every venue card shows live team distribution (e.g., 12 Argentina, 8 Brazil, 3 Mexico) — a real-time "digital crowd" that lets fans see who's watching where before they arrive.
- Multi-Sport Intelligence: The agent supports 5 sports (Soccer, Basketball, Baseball, Hockey, Football). When a user switches the sport filter, the map markers, crowd data, leaderboard rankings, and AI recommendations all re-align automatically — no preference reconfiguration needed.
Autonomy: 0 user clicks. The agent builds a live world model and surfaces intelligence on map load.
Layer 2 — Conversational Reasoning (Gemini 2.5 Pro + Vertex AI)
When a user chats with FanConnect, the agent does not just search — it reasons:
- Multi-turn Context: The agent maintains conversation history, user preferences (favorite teams, budget, vibe, languages), and real-time location. A query "where should I watch tonight?" combines match schedule data + crowd density + user budget + active promotions.
- Fallback Resilience: When Vertex AI is unreachable (no network, cold start), the agent gracefully degrades to rule-based responses backed by live data — never failing silently.
- Plan My Night: The /agent/plan endpoint orchestrates a multi-source pipeline: MongoDB aggregation (top venues by real check-ins) → match schedule parsing → promotion lookup → Gemini prompt assembly → structured JSON itinerary with Google Maps directions links.
Autonomy: The agent autonomously fetches, filters, ranks, and formats data from 4+ sources before responding — the user asks one question, the agent does 5+ operations.
Layer 3 — Partner MCP Orchestration (Multi-Agent Architecture)
FanConnect implements a multi-agent MCP architecture as required by the hackathon's Partner MCP Track:
User Query
│
▼
┌──────────────────────────────────────────────────┐
│ FanConnect Agent (Orchestrator) │
│ │
│ ┌─── Agent Tools (REST API) ──────────────────┐ │
│ │ • toggle_checkin • get_venue_status │ │
│ │ • get_city_leaderboard • get_user_history │ │
│ │ • create_venue • get_match_schedule │ │
│ │ • plan_night • search_nearby │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ┌─── FanConnect MCP Server (7 tools) ──────────┐ │
│ │ • search_nearby_venues • post_venue_event │ │
│ │ • get_active_promotions • create_promotion │ │
│ │ • find_compatible_fans • get_venue_analytics│ │
│ │ • create_match_request │ │
│ └──────────────────────────────────────────────┘ │
│ ↕ stdio │
│ ┌─── Partner: MongoDB MCP Server (24+ tools) ──┐ │
│ │ mongodb-mcp-server@latest │ │
│ │ Actively used: find, aggregate, insertOne, │ │
│ │ updateOne, createIndex, listCollections │ │
│ │ Reserve: 18+ additional tools │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
Gemini MongoDB Google Maps
Vertex AI Atlas Places API
- Agent Tools (REST API): 8 endpoints powering the core check-in and planning experience. These are the agent's primary action tools — Gemini calls them when a user asks to check in, plan a night, or find venues. All validated with Zod schemas at the API boundary.
- FanConnect MCP Server: 7 domain-specific tools for venue search, fan matching, promotions, events, and analytics — exposed via
@modelcontextprotocol/sdkover HTTP+SSE transport. This is the agent's "database intelligence" layer, bridging raw data to business logic. - Partner Integration — MongoDB MCP Server: 24+ database-level tools (
mongodb-mcp-server@latest) connected via stdio transport as a sub-agent. The agent actively callsfind,aggregate,insertOne,updateOne,createIndex, andlistCollectionsfor data operations — the remaining 18+ tools serve as extension reserve for complex queries, transactions, and index tuning. - Dual MCP Architecture: Both MCP servers run simultaneously in the Cloud Run instance. The FanConnect agent routes high-level queries to its own MCP tools (which internally delegate data access to MongoDB MCP tools), then combines results from both MCP layers with Gemini reasoning to produce coherent responses.
Autonomy: The agent decides which MCP tool to call, when to delegate to the partner MCP server, and how to compose results from multiple tools into a coherent response — all without user micromanagement.
Autonomy in Numbers
| Metric | Value |
|---|---|
| Data sources autonomously queried per "Plan My Night" | 4+ (checkins, schedule, promos, venues) |
| Agent tools available (REST + MCP + Partner MCP) | 39+ (8 REST + 7 FanConnect MCP + 24+ MongoDB MCP) |
| Sports supported (filterable) | 5 (Soccer, Basketball, Baseball, Hockey, Football) |
| Venue source types | 3 (Google Places, user-created, admin-curated) |
| Real-time update interval (crowd, checkins) | 30 seconds |
| AI models in orchestration | 2 (Gemini 2.5 Pro + Agent Builder) |
| Autonomous fallback paths | 4 (Vertex AI → rule-based → demo mode → error response) |
| User actions saved per AI interaction | 5+ (the agent does search + filter + rank + format + link) |
Why This Matters for World Cup 2026
5.4 million fans, 16 cities, 104 matches, 30+ languages. No human concierge can process this. FanConnect's agent autonomously:
- Knows the schedule — pre-loads match-aware context before the user asks
- Reads the crowd — real-time venue density from distributed fan check-ins
- Understands preferences — team, language, budget, vibe all factor into every recommendation
- Plans the night — multi-venue itinerary with directions, in one natural language request
- Degrades gracefully — every AI pathway has a deterministic fallback, so the agent never breaks
The agent doesn't wait for the user to figure out what to ask — it surfaces intelligence proactively at every layer of the experience.
Architecture
User (Browser / PWA)
│
▼
┌─────────────────┐
│ Frontend (Vite) │ React 19 + TypeScript + Google Maps API
│ Firebase Hosting│ Dark stadium theme, mobile-first 430px
└────────┬────────┘
│ REST (CORS)
▼
┌──────────────────────────────────────────────┐
│ Backend (Hono.js 4.7) — Cloud Run Gen2 │
│ ┌──────────────────────────────────────────┐│
│ │ 13 Route Modules (Zod-validated) ││
│ │ venues, users, matches, promos, events, ││
│ │ claims, agent, places, schedule, crowd, ││
│ │ notifications, mcp, checkins ││
│ ├──────────────────────────────────────────┤│
│ │ Agent Tools (8 REST endpoints) ││
│ │ checkin, leaderboard, plan, venue CRUD ││
│ │ + FanConnect MCP (7 tools via SSE) ││
│ ├──────────────────────────────────────────┤│
│ │ Partner MCP: MongoDB MCP Server ││
│ │ 24+ tools via stdio (6 actively used) ││
│ ├──────────────────────────────────────────┤│
│ │ Gemini 2.5 Pro (Vertex AI) ││
│ │ Chat, Plan My Night, Audience Insights ││
│ └──────────────────────────────────────────┘│
└────────────────────┬─────────────────────────┘
│
┌───────────┴───────────┐
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ MongoDB Atlas │ │ Google Cloud │
│ M10 dedicated │ │ ─────────────── │
│ us-central1 │ │ Vertex AI │
│ 2dsphere indexes│ │ Maps/Places API │
│ Aggregation │ │ Secret Manager │
│ Vector Search │ │ Cloud NAT + VPC │
└─────────────────┘ │ Agent Builder │
└──────────────────┘
Project Structure
FanConnect/
├── frontend/ # React 19 + Vite + TypeScript
│ ├── src/
│ │ ├── pages/ # 10 pages (lazy-loaded)
│ │ │ ├── Onboarding.tsx # Auth + value proposition
│ │ │ ├── Explore.tsx # Main map: venues, crowd, check-ins
│ │ │ ├── Schedule.tsx # 104-match schedule, tabs
│ │ │ ├── Profile.tsx # User stats + check-in history
│ │ │ ├── Settings.tsx # 3-tab: Preferences, Account, Safety
│ │ │ ├── Buddies.tsx # Fan matchmaking (hidden for pivot)
│ │ │ ├── VenueDashboard.tsx # Venue business tools
│ │ │ ├── Groups.tsx # Fan groups
│ │ │ └── PrivacyPolicy.tsx # Legal
│ │ ├── components/
│ │ │ ├── AIChat.tsx # Gemini-powered chat concierge
│ │ │ ├── LeaderboardSheet.tsx # City venue rankings
│ │ │ ├── BottomNav.tsx # 3-tab navigation
│ │ │ ├── ErrorBoundary.tsx # React error boundary
│ │ │ └── VenueBottomNav.tsx # Venue dashboard nav
│ │ ├── api/client.ts # REST client (30+ endpoints)
│ │ ├── hooks/ # useBookmarks, useApi
│ │ ├── contexts/AuthContext.tsx # Firebase Auth context
│ │ └── firebase.ts # Firebase config + auth helpers
│ ├── public/ # PWA icons, manifest
│ └── .env.production # VITE_API_URL
│
├── backend/ # Hono.js 4.7 API server
│ ├── src/
│ │ ├── index.ts # Server entry (proxy DB, 13 routes)
│ │ ├── routes/ # 13 route modules
│ │ │ ├── agent.ts # Gemini chat, Plan My Night, audience
│ │ │ ├── checkins.ts # Toggle, status, leaderboard, history
│ │ │ ├── places.ts # Discover: venues + Google Places
│ │ │ ├── venues.ts # CRUD + user-created venues
│ │ │ ├── users.ts # User registration, preferences
│ │ │ ├── matches.ts # Fan matchmaking
│ │ │ ├── promos.ts # Promotion CRUD
│ │ │ ├── events.ts # Venue events
│ │ │ ├── claims.ts # Promotion claims
│ │ │ ├── schedule.ts # WC2026 match schedule
│ │ │ ├── crowd.ts # Crowd density zones
│ │ │ ├── notifications.ts # FCM push
│ │ │ └── mcp.ts # MCP server bridge
│ │ ├── middleware/
│ │ │ ├── validate.ts # Zod schemas + validation
│ │ │ ├── rate-limit.ts # 100 req/min per IP
│ │ │ └── logger.ts # Structured JSON logging
│ │ ├── services/
│ │ │ └── mongodb-mcp-client.ts # Partner MCP integration
│ │ └── data/
│ │ └── wc2026-schedule.json # Full match schedule
│ └── Dockerfile
│
├── mcp-server/ # FanConnect MCP Server
│ ├── src/
│ │ ├── index.ts # MCP server entry (stdlib)
│ │ ├── db.ts # MongoDB Atlas connection
│ │ └── tools/ # 7 MCP tools
│ │ ├── search_nearby_venues.ts
│ │ ├── find_compatible_fans.ts
│ │ ├── get_active_promotions.ts
│ │ ├── create_match_request.ts
│ │ ├── post_venue_event.ts
│ │ ├── create_promotion.ts
│ │ └── get_venue_analytics.ts
│ └── Dockerfile
│
├── shared/ # Shared types (TypeScript package)
├── terraform/ # GCP Infrastructure as Code
│ ├── main.tf # VPC, NAT, Cloud Router
│ └── variables.tf
├── scripts/
│ └── seed.ts # DB seeder: venues, users, promos
├── cloudbuild.yaml # Cloud Build CI/CD pipeline
└── README.md
API Routes
| Method | Path | Description |
|---|---|---|
| GET | /api/discover |
Venue discovery with bbox, team, sport filters |
| GET | /api/venues/nearby |
Geo-spatial venue search |
| POST | /api/venues |
User venue creation (right-click on map) |
| GET | /api/checkins/status |
Batch check-in status for venues |
| POST | /api/checkins/toggle |
Check in / cancel check-in |
| GET | /api/checkins/leaderboard |
City venue leaderboard |
| GET | /api/checkins/user/:userId |
User check-in history + stats |
| GET | /api/schedule |
Full WC2026 match schedule |
| GET | /api/crowd |
Crowd density zones |
| POST | /api/agent/chat |
Gemini conversational AI |
| POST | /api/agent/plan |
AI "Plan My Night" itinerary |
| POST | /api/agent/audience |
AI audience suggestion for venues |
| GET | /api/agent/status |
Agent health + MCP tool listing |
| POST | /api/users/register |
Register/login user |
| PUT | /api/users/:id |
Update user preferences |
| DELETE | /api/users/:id |
Delete account |
| POST | /api/users/:id/report |
Report a user |
| GET | /api/promos/active |
Active promotions near location |
| POST | /api/promos |
Create promotion |
| POST | /api/claims/:promoId |
Claim a promotion |
| GET | /api/events |
Venue events |
| POST | /api/events |
Create venue event |
| GET | /api/mcp/status |
MCP server health |
| POST | /api/notifications/subscribe |
FCM token registration |
| GET | /health |
DB + MCP + API health check |
Tech Stack
| Layer | Technology |
|---|---|
| Frontend | React 19, Vite 6, TypeScript 5.8, Lucide React |
| Maps | @vis.gl/react-google-maps, Google Maps JS API |
| Backend | Hono.js 4.7, MongoDB driver 6.15, Zod 3.24 |
| AI Engine | Gemini 2.5 Pro (Vertex AI), Google Cloud Agent Builder |
| MCP (FanConnect) | @modelcontextprotocol/sdk 1.13, HTTP+SSE transport, 7 tools |
| Partner MCP | mongodb-mcp-server (24+ tools, 6 actively called: find, aggregate, insertOne, updateOne, createIndex, listCollections) |
| Database | MongoDB Atlas M10 (2dsphere, aggregations) |
| Auth | Firebase Auth (Google Sign-In + Email/Password) |
| Hosting | Firebase Hosting (frontend), Cloud Run Gen2 (backend) |
| Infrastructure | Terraform (VPC, NAT, Connector), Secret Manager |
| CI/CD | Cloud Build, gcloud builds submit |
| Push | Firebase Cloud Messaging |
Deploy
Frontend
cd frontend
npm run build
GOOGLE_APPLICATION_CREDENTIALS="firebase-service-account.json" \
npx firebase deploy --only hosting --project=fanconnect-499021
Backend
cd backend
gcloud builds submit --project=fanconnect-499021 --tag gcr.io/fanconnect-499021/backend
gcloud run deploy fanconnect-backend \
--project=fanconnect-499021 --region=us-central1 \
--image gcr.io/fanconnect-499021/backend \
--vpc-connector projects/fanconnect-499021/locations/us-central1/connectors/fanconnect-connector \
--vpc-egress all-traffic
Live URLs
| Component | URL |
|---|---|
| Frontend | https://fanconnect-499021.web.app |
| Backend API | https://fanconnect-backend-463373359828.us-central1.run.app |
| API Health | https://fanconnect-backend-463373359828.us-central1.run.app/health |
| Agent Status | https://fanconnect-backend-463373359828.us-central1.run.app/api/agent/status |
Design System
- Theme: Dark stadium atmosphere (
#0A0E1Aprimary,#D4AF37gold,#6366F1AI purple) - Icons: Lucide (thin-stroke, MIT license)
- Typography: System font stack, mobile-first 430px max-width
- CSS: 24 custom properties (
var(--bg-primary),var(--ai-purple), etc.) - Animations: CSS transitions (0.15s–0.2s), spin loader keyframe
Log in or sign up for Devpost to join the conversation.