🏃‍♂️ Parkour·Spot

A cross-platform Flutter application for discovering, reporting, and rating parkour spots. Built with Firebase backend services and modern Flutter architecture.

🌐 Live App: https://Parkour.Spot

✨ Features

• 🔐 User Authentication - Sign up, login, and profile management
• 📍 Spot Discovery - Browse and search parkour spots
• 🗺️ Interactive Maps - View spots on maps with location data
• 📱 Add New Spots - Report new parkour locations with photos
• ⭐ Rating System - Rate and review spots
• 📱 Progressive Web App - Works on Web, Mobile, and Desktop via Progressive Web App
• ☁️ Cloud Backend - Firebase-powered with real-time data sync

🚀 Development

Prerequisites

• Flutter SDK: 3.9.0 or higher
• Dart SDK: 3.9.0 or higher
• Firebase CLI: Latest version
• Node.js: 18.0.0 or higher

Setup

1. Clone the Repository

git clone <your-repo-url>
cd Parkour.Spot

2. Run Setup Script

chmod +x setup.sh
./setup.sh

The setup script will:

• Check Flutter and Firebase CLI installation
• Install Flutter dependencies
• Initialize Firebase project
• Configure FlutterFire
• Initialize emulator seed data (for local development)

Local Development

There are two development flows depending on whether you have access to the production Firebase project:

Option 1: Using Firebase Emulators (Recommended for Most Developers)

This is the recommended approach for most developers. No Firebase production access required.

# Terminal 1: Start Firebase emulators
./scripts/start_emulators.sh

# Terminal 2: Run the app with emulators
./scripts/run_local_with_emulators.sh

🌱 Emulator Seed Data: When you start emulators for the first time, seed data from scripts/seed-data/ is automatically copied to .firebase/emulator-data/. This gives you a working dataset with test users, spots, and other sample data to develop with. Your changes are automatically saved when you stop the emulators.

Seed data reference. The committed export includes at least four users and sample content:

• user@parkour.spot — Password: user@parkour.spot. Regular user.
• moderator@parkour.spot — Password: moderator@parkour.spot. Moderator.
• admin@parkour.spot — Password: admin@parkour.spot. Admin.
• google@parkour.spot — Sign in with Google (not email/password). Regular user.

There are at least two parkour spots in Évry-Courcouronnes, France.

🖥️ Emulator UI (http://localhost:4000): The Firebase Emulator Suite provides a web UI for managing your local emulators. Use it to:

• Create users: Go to Authentication → Users → Add user (email/password)
• Verify email: Open a user → Edit → toggle "Email verified" on
• View Firestore data: Browse collections and documents
• Inspect Storage: See uploaded files
• Debug Functions: View logs and trace invocations

Option 2: Using Firebase Production Instance

Only for developers with access to the production Firebase project.

1. Environment Configuration

cp env.example .env
# Edit .env with your Firebase configuration

Required environment variables:

# Firebase Configuration
FIREBASE_API_KEY=your_api_key_here
FIREBASE_APP_ID_WEB=your_web_app_id_here
FIREBASE_MESSAGING_SENDER_ID=your_sender_id_here
FIREBASE_PROJECT_ID=your_project_id_here
FIREBASE_AUTH_DOMAIN=parkour.spot
FIREBASE_STORAGE_BUCKET=your_project_id.firebasestorage.app
FIREBASE_MEASUREMENT_ID=your_measurement_id_here

2. Run the App

./scripts/run_production.sh

Backend Google Maps API Key

The autocomplete and geocoding features use a server-side Google Maps API key via Firebase Functions secrets. Make sure to set the secret in your Firebase project:

firebase functions:secrets:set GOOGLE_MAPS_API_KEY

This key should have at least the following APIs enabled:

• Places API
• Geocoding API

The Flutter client calls callable functions placesAutocomplete, placeDetails, geocodeCoordinates, and reverseGeocodeAddress, which proxy Google APIs securely using the backend key.

Common Workflows

Production Build

# Build for production
./scripts/build_production.sh

Firebase Deployment

# Deploy hosting
firebase deploy --only hosting

# Deploy functions
firebase deploy --only functions

# Deploy indexes
firebase deploy --only firestore:indexes

Other Development Scripts

# Development build
./scripts/build_development.sh

Testing

• Flutter/Dart (unit tests for lib/ utilities and widgets):

  flutter test

• Cloud Functions (unit tests for helper logic in functions/):

  cd functions && npm test

Emulator Data Management

The project includes seed data for Firebase emulators to help new developers get started quickly. Test accounts and sample spots are documented in the Seed data reference subsection under Option 1: Using Firebase Emulators above.

Available Scripts:

# Reset emulator data to seed data
./scripts/clear_emulator_data.sh

# Update seed data from current emulator data
./scripts/update_seed_data.sh

# Export emulator data manually (if needed)
./scripts/export_emulator_data.sh

How It Works:

• Seed Data: Located in scripts/seed-data/, this is committed to the repository and provides initial test data
• Emulator Data: Located in .firebase/emulator-data/ (gitignored), this is your local development data
• Auto-Initialization: When you run ./scripts/start_emulators.sh for the first time, seed data is automatically copied to emulator data
• Auto-Export: When you stop emulators (Ctrl+C), your data is automatically exported to .firebase/emulator-data/
• Reset: Use ./scripts/clear_emulator_data.sh to reset your emulator data back to seed data
• Update Seed: Use ./scripts/update_seed_data.sh to update the seed data that new developers will receive

🏗️ Architecture

[Flutter App (Mobile/Web)] 
    ↕️
[REST API (Cloud Functions)] 
    ↕️
[Database (Firestore)] 
    ↕️
[Cloud Storage (Firebase Storage)] 
    ↕️
[Authentication (Firebase Auth)]

📁 Project Structure

lib/
├── main.dart                 # App entry point
├── models/                   # Data models
│   ├── spot.dart            # Parkour spot model
│   ├── user.dart            # User model
│   └── rating.dart          # Rating model
├── services/                 # Business logic
│   ├── auth_service.dart    # Authentication
│   ├── spot_service.dart    # Spot management
│   └── share_service_*.dart # Platform-specific sharing
├── screens/                  # UI screens
│   ├── auth/                # Login/signup
│   ├── spots/               # Spot-related screens
│   └── profile/             # User profile
├── widgets/                  # Reusable components
└── router/                  # Navigation and routing

🗄️ Data Models

Spots Collection

{
  "name": "String",
  "description": "String", 
  "location": "GeoPoint",
  "imageUrls": "List<String>?",
  "rating": "Double?",
  "ratingCount": "Int?",
  "tags": "List<String>?",
  "createdBy": "String",
  "createdAt": "Timestamp",
  "updatedAt": "Timestamp"
}

Users Collection

{
  "id": "String",
  "email": "String",
  "displayName": "String?",
  "photoURL": "String?",
  "createdAt": "Timestamp",
  "lastLoginAt": "Timestamp",
  "favoriteSpots": "List<String>?"
}

Ratings Collection

{
  "id": "String",
  "spotId": "String",
  "userId": "String",
  "rating": "Double",
  "createdAt": "Timestamp?",
  "updatedAt": "Timestamp?"
}

🔑 Key Dependencies

• firebase_core: Firebase initialization
• firebase_auth: User authentication
• cloud_firestore: Database operations
• firebase_storage: Image storage
• cloud_functions: Backend functions
• provider: State management
• geolocator: Location services
• image_picker: Photo selection

🔧 Troubleshooting

Common Issues

Firebase Configuration

• Ensure .env file exists with correct values
• Run flutterfire configure if Firebase options are missing
• Check Firebase project permissions

Web Build Issues

flutter config --enable-web
flutter clean
flutter build web

Useful Commands

# Clean build
flutter clean
flutter pub get

# Check Flutter doctor
flutter doctor

# Update Flutter
flutter upgrade

📱 Platform Support

Platform	Status	Notes
Web	✅ Ready	Firebase Hosting + PWA
Mobile Web	✅ Ready	Works on iOS Safari, Android Chrome
PWA	✅ Ready	Installable on mobile devices

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly on all platforms
5. Submit a pull request

Code Style

• Follow Flutter Style Guide
• Use meaningful variable and function names
• Add comments for complex logic
• Keep functions small and focused

Testing

• Write unit tests for services
• Test UI components with widget tests
• Ensure all new features have tests

📚 Resources

• Flutter Documentation
• Firebase Documentation
• Dart Language Tour
• Flutter Widget Catalog

📄 License

This project is licensed under the MIT License.

---

Built with ❤️ using Flutter and Firebase