Explore Hamilton - Gamified City Exploration App

A mobile app for discovering and exploring Hamilton, Ontario through gamified location check-ins, events, and social features. Built with React Native, Expo, and PocketBase.

App Screens

Features

• 🗺️ Interactive Map - Explore Hamilton with custom location and event markers
• 🏗️ Steel City Theme - Sage green design celebrating Hamilton's industrial heritage
• 🎯 Gamified Exploration - Earn points and badges for visiting locations and attending events
• 👥 Friends System - Connect with other Hamilton explorers and view their profiles
• 📅 Events & RSVPs - Discover local events and RSVP with your friends
• 📍 Location Check-ins - Check into Hamilton locations to earn points and leave reviews
• 🏆 Leaderboard - Compete with friends on exploration rankings
• ⭐ Reviews & Ratings - Share your experiences at Hamilton locations
• 🏅 Achievement System - Unlock badges as you explore more of the city
• 👤 User Profiles - Detailed profiles showing stats, achievements, and recent activity

Requirements

⚠️ Important: This setup guide is specifically for macOS with an iPhone for testing.

Hardware

• MacBook (macOS)
• iPhone (for testing via Expo Go)
• Both devices must be on the same WiFi network

Software

• Node.js (v18 or higher)
• Homebrew (for installing PocketBase)
• Expo Go app installed on your iPhone

Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/explore-hamilton-app.git
cd explore-hamilton-app

2. Install PocketBase

brew install pocketbase

3. Start the Backend

Open a terminal window and run:

cd backend
pocketbase serve --http="0.0.0.0:8090"

The backend will start at http://127.0.0.1:8090

• Admin Dashboard: http://127.0.0.1:8090/_/
• The database (pb_data/) is pre-populated with 18 Hamilton locations and 6 events

Note: Using 0.0.0.0:8090 allows your iPhone to connect to the backend over your local network.

4. Install Frontend Dependencies

Open a new terminal window and run:

cd frontend
npm install

5. Start the Frontend

npx expo start

This will display a QR code in the terminal.

6. Run on Your iPhone

1. Open the Camera app on your iPhone
2. Scan the QR code displayed in the terminal
3. Tap the notification to open in Expo Go

The app will automatically detect your Mac's IP address and connect to the PocketBase backend.

Project Structure

explore-hamilton/
├── backend/
│   ├── pb_data/              # PocketBase database & uploads
│   └── pb_migrations/        # Database migrations
├── frontend/
│   ├── app/
│   │   ├── (tabs)/          # Tab screens (home, explore, leaderboard, friends, account)
│   │   │   ├── index.tsx    # Home screen (placeholder)
│   │   │   ├── explore.tsx  # Map with locations & events
│   │   │   ├── leaderboard.tsx  # User rankings
│   │   │   ├── friends.tsx  # Friends list & search
│   │   │   └── account.tsx  # Profile & achievements
│   │   ├── event/[id].tsx   # Event detail & RSVP
│   │   ├── location/[id].tsx # Location detail & check-in
│   │   └── user/[id].tsx    # User profile pages
│   ├── lib/
│   │   └── pocketbase.ts    # PocketBase client & types
│   ├── constants/
│   │   └── theme.ts         # Sage green color scheme
│   └── assets/              # Fonts and images
└── README.md

Database Schema

Collection	Description	Records
users	User accounts with points & bios	5 users
locations	Hamilton locations (parks, cafes, landmarks)	18 locations
events	Hamilton events (Art Crawl, markets, sports)	6 events
event_rsvps	Event RSVP tracking	7 RSVPs
check_ins	Location check-ins with points	5 check-ins
friendships	Bidirectional friend connections	12 friendships
achievements	Badge definitions	3 badges
user_achievements	Earned user badges	6 earned
reviews	Location & event reviews	14 reviews
favorites	User's favorite locations	15 favorites
activity_feed	User activity tracking	12 activities

Hamilton Locations Included

Parks & Outdoor

• Gage Park - Hamilton's premier park with gardens and trails
• Bayfront Park - Waterfront park with stunning harbor views
• Dundurn Castle - Historic castle and gardens
• Royal Botanical Gardens - World-renowned botanical gardens

Food & Dining

• The Cannon - Local brewery and restaurant
• Merit Brewing Company - Craft brewery in Hamilton
• The Ship - Traditional pub and eatery
• Fortinos - Hamilton grocery chain

Culture & Arts

• Art Gallery of Hamilton - Premier art museum
• Theatre Aquarius - Professional theatre company
• Hamilton Museum of Steam & Technology - Industrial heritage
• James Street North - Arts district

Entertainment

• FirstOntario Centre - Sports and entertainment venue
• Tim Hortons Field - Hamilton Tiger-Cats stadium
• Locke Street - Shopping and dining district

Events Included

• 🎨 Hamilton Art Crawl - Monthly arts event on James Street North
• 🛒 Hamilton Farmers' Market - Saturday market at York Boulevard
• 🎵 Gage Park Summer Festival - Annual music and food festival
• 🏈 Hamilton Tiger-Cats Game - CFL football at Tim Hortons Field
• 🎭 Theatre Aquarius Production - Professional theatre performances
• 🍺 Merit Brewing Trivia Night - Weekly trivia at local brewery

Troubleshooting

"Network request failed" error

• Ensure both your Mac and iPhone are on the same WiFi network
• Check that PocketBase is running with --http="0.0.0.0:8090"
• Restart the Expo server with npx expo start --clear

"Failed to create record" error

• Open PocketBase admin at http://127.0.0.1:8090/_/
• Go to each collection → API Rules tab
• Temporarily set Create, List/Search, and View rules to empty (for testing)
• This allows public access during development

App not updating after code changes

• Shake your iPhone and tap "Reload"
• Or press r in the Expo terminal

"Project is incompatible with this version of Expo Go"

• Update Expo Go app on your iPhone to the latest version
• Ensure your project uses compatible Expo SDK version (54+)

PocketBase admin login

On first run, create an admin account at http://127.0.0.1:8090/_/ to access the database

Key Features Implemented

✅ Explore/Map Screen

• Interactive map centered on Hamilton, Ontario
• Custom location markers with category-based colors
• Event markers with calendar icons
• View mode toggle: All / Locations / Events
• Category filtering (Parks, Food, Cafes, Bars, Museums, etc.)
• Custom callouts with navigation to detail screens
• Map legend and results count
• Pull-to-refresh functionality

✅ Friends System

• Friends list with user profiles
• "People You May Know" suggestions
• Friend search with debounced queries
• Add/remove friend functionality
• User profile pages with stats, achievements, and activity
• Friend request status tracking

✅ Leaderboard

• User rankings sorted by points
• Medal emojis for top 3 users
• Special styling for rankings
• User cards with avatars and bios

✅ Account/Profile System

• Achievement unlock banners
• Badge display (earned vs locked)
• User stats grid (badges, points, check-ins)
• Profile customization

✅ Event & Location Details

• Detailed event pages with RSVP functionality
• Location pages with check-in capability
• Maps showing exact locations
• Directions integration
• Review and rating systems

Tech Stack

• Frontend: React Native, Expo Router, TypeScript
• Backend: PocketBase (SQLite)
• Maps: react-native-maps with custom markers
• State Management: React Hooks
• Styling: StyleSheet with custom sage green theme
• Fonts: Nunito (Regular, SemiBold, Bold)
• Icons: Custom steel beam icons and geometric shapes

Design System

Colors (Sage Green Theme)

Colors: {
  primary: '#6B9B6B',        // Steel city sage green
  primaryDark: '#5A8A5A',
  primaryLight: '#8BB88B',
  background: '#FFFFFF',
  textOnPrimary: '#FFFFFF',
}

Typography

• Headers: Nunito Bold (28-32px)
• Body: Nunito Regular (14-16px)
• UI Elements: Nunito SemiBold (12-18px)

Iconography

• Steel Beam Icon: Custom I-beam shape representing Hamilton's steel industry
• Tab Icons: Geometric shapes (house, map pin, bar chart, people, profile)
• Category Icons: Emoji-based system for quick recognition

Sample Data

The repository includes comprehensive seed data:

Users (5 total)

• Alexis Quilatan - 230 points (Explorer status)
• Nithika Karunamoo - 190 points (Explorer status)
• Rosa Chen - 120 points (Adventurer status)
• Sylvia Kamel - 85 points (Local status)
• Yevgeniy Sigayev - 60 points (Local status)

Achievements

• First Steps - Complete your first check-in
• Explorer - Visit 5 different locations
• Adventurer - Attend 3 events

All users have realistic Hamilton connections with proper friend networks and activity histories.

Development Status

✅ Completed Features

• Complete backend setup with 11 PocketBase collections
• Fully implemented Explore/Map screen with filtering
• Comprehensive Friends system with search and profiles
• Leaderboard with user rankings
• Event and Location detail pages with actions
• User profile pages with stats and activity
• Consistent sage green theme throughout

🚧 In Progress

• Home screen with featured events carousel
• Authentication system (login/signup)
• Real-time notifications
• Image upload for reviews

📋 Future Enhancements

• Push notifications for friend activities
• Event photo sharing
• Location-based achievements
• Integration with Hamilton tourism data
• Social media sharing
• Advanced search and filtering

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details

---

Explore Hamilton - Discover the Steel City through gamified exploration! 🏗️🗺️