-
-
Top Three - AI Powered Poker Run
-
Create an Outing using Yelp AI API
-
Click the mic to use natural language to describe the adventure
-
Read and hear the spoken response from the Yelp AI
-
Select 3 locations and travel to the 1st destination
-
Checkin to receive your first card, up to 4 players can play
-
Travel to the next spot to receive your 2nd card
-
Travel to the final spot and complete the game
-
Review the leaderboard for the final results
Inspiration
The inspiration for Top Three Poker Run came from a simple desire to make everyday adventures more exciting and competitive. We wanted to combine the thrill of discovery with the strategic fun of poker, creating a unique way for people to explore their cities while competing with friends.
Traditional poker runs require physical cards and manual check-ins, but we saw an opportunity to modernize this experience using location technology and AI-powered search. The Yelp AI API was the perfect catalyst—it allowed us to create a conversational, natural language search experience that makes finding great local businesses as easy as describing what you want to do. Instead of scrolling through endless lists, users can simply say "Find me the best pizza places downtown" and let AI do the work.
What it does
Top Three Poker Run transforms any outing into a competitive poker game. Here's how it works:
Create an Outing: Users describe what they want to do using natural language—either by typing or speaking. The app uses the Yelp AI API to understand their intent and find relevant locations.
Select Locations: Users choose 3 venues from AI-powered search results, each sorted by distance and relevance.
Start the Adventure: Once an outing is published, users navigate to each location using GPS.
Check In: When users arrive at a location, the app verifies they're within 50 meters using GPS coordinates and the Haversine distance formula. This ensures fair play while accounting for GPS inaccuracy.
Collect Cards: At each check-in, users receive a playing card. After visiting all three locations, they receive 2 additional cards to complete their 5-card poker hand.
See Results: The app automatically ranks poker hands (Royal Flush, Straight Flush, Four of a Kind, etc.) and displays a leaderboard comparing all players' hands.
The app works seamlessly across iOS, Android, and Web platforms, with voice activation, real-time GPS tracking, and beautiful animations that make the experience engaging and fun.
How we built it
Architecture: We chose React Native with Expo SDK 54 for its cross-platform capabilities and rapid development cycle. Expo Router provided file-based routing that made navigation intuitive, while TypeScript ensured type safety throughout the codebase.
Yelp AI Integration: The app uses the Yelp AI API (/ai/chat/v2) as the primary data source, with intelligent fallback to the Fusion API for reliability. We created a service layer that handles both APIs seamlessly, parsing natural language queries and returning relevant businesses sorted by distance. The AI's conversational interface guides users to better search results.
Voice Activation: We implemented platform-specific speech recognition to provide a hands-free experience:
- Web: Web Speech API with continuous recognition and 8-second pause detection
- iOS: Native SFSpeechRecognizer via expo-speech-recognition
- Android: Native SpeechRecognizer via expo-speech-recognition
GPS Check-In System: Using expo-location, we track user position in real-time and calculate distance using the Haversine formula. The system verifies users are within a configurable distance threshold (default 50 meters) before allowing check-in, ensuring fair play while being forgiving of GPS inaccuracy.
Poker Game Logic: We implemented full 5-card poker hand rankings with animated card dealing. The system deals 3 cards during active outings and 2 final cards on completion, supporting all standard poker hands from High Card to Royal Flush.
Data Persistence: AsyncStorage handles local data persistence, allowing users to save and manage multiple outings without requiring a backend server. This keeps the app fast and works offline.
Cross-Platform Compatibility: We created platform-aware components, including an Icon component that uses emoji on web and native Ionicons on mobile, ensuring consistent appearance across all platforms.
Development Environment: This entire project was built in just 4 days using Cursor IDE with AI-powered development. The project was brought to life through collaboration between the developer and 4 specialized AI agents, each handling different aspects of the project:
- Project Requirements Agent: Ensured all hackathon requirements were met
- Judge Criteria Agent: Reviewed and optimized for judging criteria
- Submission Requirements Agent: Managed submission documentation and requirements
- Process Documentation Agent: Documented challenges, solutions, and learnings
This AI-assisted development approach allowed for rapid iteration, comprehensive problem-solving, and production-ready code in record time.
Challenges we ran into
Cross-Platform Icon Rendering: One of our biggest challenges was getting icons to display correctly on web. The @expo/vector-icons package uses font files that weren't being served correctly on Vercel, causing icons to appear as empty boxes. We solved this by creating a platform-aware Icon component that uses emoji on web and native Ionicons on mobile platforms.
Voice Recognition Timing: Getting the pause detection right for voice input was tricky. We experimented with different timeout values (2s, 5s, 8s) and learned that continuous recognition with custom pause detection provides the best user experience. We also had to handle platform-specific quirks, like Firefox not supporting the Web Speech API.
Font Loading on Web: The font files for Ionicons were being requested from incorrect paths in the deployed build, causing "Failed to decode downloaded font" errors. We resolved this by disabling font loading on web and using CSS-based icon fallbacks, which eliminated the errors while maintaining functionality.
GPS Accuracy: Balancing check-in distance requirements was challenging. Too strict (10 meters) and users couldn't check in due to GPS inaccuracy. Too lenient (100+ meters) and the system loses its anti-cheating effectiveness. We settled on 50 meters with configurable distance minimums for testing, allowing flexibility while maintaining integrity.
Yelp API Rate Limits: During development, we hit Yelp API rate limits frequently. We implemented intelligent caching, fallback to mock data during development, and clear error messages to guide users when rate limits are exceeded.
Web Deployment Routing: Getting client-side routing to work correctly on Vercel required adding a vercel.json configuration with rewrite rules to serve index.html for all routes, allowing Expo Router to handle navigation properly. Initially, we were deploying from the wrong directory, which caused 404 errors.
Build Configuration: Configuring EAS Build for iOS from a Windows machine required learning the EAS Build workflow and understanding how to properly structure the build configuration for different environments. We also had to resolve React version conflicts using legacy-peer-deps.
Accomplishments that we're proud of
✅ Full Cross-Platform Support: Successfully built a single codebase that works seamlessly on iOS, Android, and Web, with platform-specific optimizations for each.
✅ Yelp AI API Integration: Successfully integrated the Yelp AI API as the primary data source, creating a conversational search experience that understands natural language queries like "Find me restaurants on False River with a view."
✅ Voice-First Experience: Implemented real-time speech recognition across all three platforms, allowing users to create outings hands-free with natural conversation.
✅ Fair GPS Verification: Created a robust check-in system using the Haversine formula that balances user experience with anti-cheating measures, configurable for different use cases.
✅ Complete Poker Game Logic: Implemented full 5-card poker hand rankings with beautiful animated card dealing, supporting all standard poker hands.
What we learned
Cross-Platform Development: Building for iOS, Android, and Web simultaneously taught us the importance of platform-specific optimizations. We learned to handle differences in speech recognition APIs (Web Speech API vs. native iOS/Android), font rendering (CSS-based icons on web vs. font files on native), and navigation patterns. The key was creating abstraction layers that hide platform differences while leveraging platform strengths.
Yelp AI API Integration: Working with the Yelp AI API (/ai/chat/v2) was particularly enlightening. We discovered how to structure conversational queries that produce better results, how to handle AI responses that guide users, and how to gracefully fall back to the Fusion API when needed. The AI's ability to understand natural language queries transformed how users interact with location search.
Voice-First Design: Implementing voice activation across three platforms revealed the complexity of real-time speech recognition. We learned to handle different pause detection strategies, manage continuous recognition, and create a seamless experience whether users are typing or speaking. The challenge was making it feel natural while handling edge cases like background noise and speech interruptions.
GPS Accuracy: Implementing fair check-in verification required understanding the Haversine formula for distance calculation and balancing user experience with anti-cheating measures. We learned that 50 meters is the sweet spot—close enough to ensure authenticity, but forgiving enough for GPS inaccuracy. We also learned the importance of making systems configurable for different testing scenarios.
Web Deployment: Deploying a React Native app to the web taught us about client-side routing, static asset serving, and platform-specific build configurations. We learned that sometimes the simplest solution (emoji icons) is better than fighting with complex font loading systems.
What's next for Top Five Poker Run
Social Features: We plan to add real-time multiplayer support, allowing friends to join outings and compete in real-time. This will include push notifications when players check in and live leaderboard updates.
Advanced Analytics: We want to add statistics tracking—showing users their favorite locations, most common poker hands, and adventure streaks. This will help users discover patterns in their exploration habits.
Location Sharing: Implement the ability to share outings with friends via links, making it easy to invite others to join poker runs.
Backend Integration: While the app currently works offline with AsyncStorage, we plan to add cloud sync so users can access their outings across devices and share data with friends.
Enhanced AI Features: Expand the Yelp AI integration to provide personalized recommendations based on user history and preferences, making each search smarter than the last.
Tournament Mode: Create organized tournaments with multiple outings, brackets, and prizes, taking the competitive aspect to the next level.
AR Integration: Explore augmented reality features that could overlay card information or location details in the camera view, making the experience even more immersive.
The foundation is solid, and we're excited to continue building features that make exploring cities more fun and competitive!
Built With
- asyncstorage
- cursoride
- eas
- expo-location
- expo-speech
- expo-speech-recognition
- expo.io
- node.js
- npm
- react-native
- typescript
- vercel
- webspeechapi
- yelpaiapi
- yelpfusionapi