🌱 FitQuest

Transform daily wellness activities into an engaging adventure

Features • Getting Started • Documentation • Contributing

🎯 Project Overview

FitQuest combines wellness tracking with gamification mechanics to create an engaging experience that motivates users to maintain healthy habits. Complete daily activities to earn XP and watch your virtual plant companion evolve from a tiny seed to a majestic ancient tree.

💪 How It Works

Earn XP by completing daily wellness activities:

🏃 Exercise: 50 XP per session (cardio, strength, yoga)
🧘 Meditation: 30 XP per session (5+ minutes)
💧 Hydration: 10 XP per glass (track your water intake)
😴 Sleep: 40 XP for 7-9 hours of quality rest

🌳 Plant Evolution Stages

Watch your companion grow through 5 unique stages:

Seed (0-100 XP) - Just beginning your journey
Sprout (100-500 XP) - First signs of growth
Sapling (500-1500 XP) - Building strong habits
Tree (1500-5000 XP) - Thriving wellness routine
Ancient Tree (5000+ XP) - Master of healthy living

✨ Key Features

🎮 Core Gameplay

🌟 Evolving Plant Companion - Watch your companion grow through 5 evolution stages as you progress
🎯 XP System - Earn experience points for completing wellness activities
🔥 Streak Tracking - Maintain daily streaks to maximize your growth
⚡ Combo Multipliers - Complete multiple activities for bonus XP

📊 Tracking & Analytics

📈 Activity Dashboard - Visualize your progress with beautiful charts
📅 Calendar View - Track your consistency over time
💎 Weekly Goals - Set and achieve personalized targets
🎯 Activity History - Review all your logged activities

🏆 Social & Competition

🥇 Global Leaderboards - Compete with users worldwide
👥 Friends System - Connect and challenge friends
🏅 Achievement System - Unlock 15+ unique badges
🎊 Milestone Celebrations - Celebrate your progress with animations

🔧 User Experience

🌓 Dark Mode - Beautiful UI in light and dark themes
🔔 Smart Notifications - Timely reminders to maintain your streak
📱 Offline-First - Works seamlessly without internet connection
🌍 Multi-language Support - Available in multiple languages (coming soon)
♿ Accessibility - Designed with accessibility in mind

🛠️ Tech Stack

Frontend

Framework: Flutter 3.16.0
Language: Dart 3.0+
State Management: BLoC Pattern + Provider (for theme)
Animations: Rive (plant animations), Lottie (UI animations), Custom Painters
UI Components: Custom design system with Material 3

Backend & Services

Authentication: Firebase Auth (Email/Password, Google Sign-In)
Database: Cloud Firestore (NoSQL, real-time sync, 40 MB cache limit)
Storage: Firebase Cloud Storage (user avatars, plant images)
Functions: Cloud Functions for Firebase (leaderboard calculations)
Analytics: Firebase Analytics & Crashlytics

Architecture & Patterns

Architecture: Clean Architecture with Repository Pattern
Dependency Injection: GetIt + Injectable
Local Storage: Hive (offline data), Shared Preferences (settings)
Code Generation: Freezed, Json Serializable, Injectable
Testing: Unit tests (mockito), Widget tests, Integration tests

📖 Documentation: See the docs/ folder for technical documentation.

📋 Prerequisites

Before you begin, ensure you have the following installed:

✅ Flutter SDK (3.16.0 or higher) - Install Flutter
✅ Dart SDK (3.0.0 or higher) - Included with Flutter
✅ Android Studio or Xcode (for mobile development)
✅ VS Code with Flutter extensions (recommended) - Setup VS Code
✅ Git - Install Git
✅ Firebase Account - Create Firebase Account

Verify Installation

flutter doctor -v

🚀 Getting Started

1️⃣ Clone the Repository

git clone https://github.com/NickiMash17/fitquest-app.git
cd fitquest-app

2️⃣ Install Dependencies

flutter pub get

3️⃣ Set up Firebase

a. Create a Firebase Project

Visit Firebase Console
Click "Add project"
Enter project name: fitquest-app
Follow the setup wizard (disable Google Analytics for development)

b. Enable Required Services

Authentication
- Go to Authentication → Sign-in method
- Enable Email/Password
- Enable Google (optional)
Firestore Database
- Go to Firestore Database
- Click "Create database"
- Start in Test mode (for development)
- Choose your region
Storage
- Go to Storage
- Click "Get started"
- Start in Test mode

c. Add Your App to Firebase

For Android:

Click the Android icon in Project Overview
Register app with package name: com.nicolettemashaba.fitquest
Download google-services.json
Place it in android/app/ directory

For iOS:

Click the iOS icon in Project Overview
Register app with bundle ID: com.nicolettemashaba.fitquest
Download GoogleService-Info.plist
Place it in ios/Runner/ directory

d. Configure FlutterFire CLI

# Install FlutterFire CLI globally
dart pub global activate flutterfire_cli

# Configure Firebase for your project
flutterfire configure

Follow the prompts and select your Firebase project.

4️⃣ Run the App

# Run on Chrome (Web)
flutter run -d chrome

# Run on Android Emulator
flutter run -d android

# Run on iOS Simulator (Mac only)
flutter run -d ios

# Run on specific device
flutter devices  # List available devices
flutter run -d <device-id>

5️⃣ Build for Production

Android (APK)

flutter build apk --release

Android (App Bundle - for Play Store)

flutter build appbundle --release

iOS (Mac only)

flutter build ipa --release

Web

flutter build web --release

📁 Project Structure

lib/
├── core/                    # Core functionality (config, constants, services, theme)
│   ├── constants/          # App constants, colors, strings
│   ├── theme/             # Theme data, text styles
│   ├── utils/             # Helper functions, validators
│   ├── config/            # App configuration
│   ├── services/          # Core services
│   └── widgets/           # Core reusable widgets
├── features/                # Feature modules (feature-based structure)
│   ├── authentication/     # Auth feature (BLoC, pages, widgets)
│   ├── activities/         # Activity tracking feature
│   ├── home/               # Home screen feature
│   ├── goals/              # Goals feature
│   ├── profile/            # User profile, settings
│   ├── community/          # Leaderboards, friends, social features
│   └── onboarding/         # First-time user experience
├── shared/                  # Shared code across features
│   ├── models/             # Data models (Freezed)
│   ├── repositories/       # Data repositories
│   ├── services/           # Business logic services
│   └── widgets/            # Reusable widgets
└── main.dart               # App entry point

🧪 Testing

Run All Tests

flutter test

Run Tests with Coverage

flutter test --coverage
lcov --list coverage/lcov.info  # View coverage summary

Run Integration Tests

flutter test integration_test/

Run Specific Test File

flutter test test/features/authentication/bloc/auth_bloc_test.dart

Test Categories

Unit Tests - Business logic, utilities, models
Widget Tests - UI components, interactions
Integration Tests - End-to-end user flows
Golden Tests - Visual regression testing (coming soon)

📚 Documentation

Technical Deep Dive - Architecture, design decisions, and implementation details

🗺️ Roadmap

✅ Completed

🚧 In Progress (Q1 2025)

📅 Planned (Q2 2025)

Social features (friends, challenges)
Custom plant themes and shop
Apple Health / Google Fit integration
Advanced analytics dashboard
Multi-language support

🔮 Future (Q3 2025+)

AI-powered habit recommendations
Community challenges
Premium subscription tier
Wearable device integration
Desktop applications (Windows, macOS)

🐛 Troubleshooting

Common Issues

1. Blank Screen on Web

Symptoms: White/blank screen when running on web browser

Solutions:

Check Browser Console (F12 → Console tab) for errors
Hard Refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
Clear Browser Cache: Ctrl+Shift+Delete → Clear cached images and files
Try Incognito Mode: Open browser in incognito and navigate to localhost

2. Firebase Configuration Errors

Symptoms: No Firebase App '[DEFAULT]' has been created

Solutions:

# Re-run FlutterFire configuration
flutterfire configure

# Ensure google-services.json and GoogleService-Info.plist are in correct locations
# Clean and rebuild
flutter clean
flutter pub get
flutter run

3. Firestore Index Errors

Symptoms: Console warnings about missing indexes

Solutions:

These are warnings, not critical errors
Click the provided link in the error message
Firebase Console will auto-generate the required index
Wait 2-5 minutes for index creation

4. Build Errors After Updating Dependencies

Solutions:

flutter clean
flutter pub get
flutter pub upgrade
flutter run

5. Port Already in Use (Web)

Symptoms: Port 8080 is already in use

Solutions:

# Use a different port
flutter run -d chrome --web-port=8081

# Or kill the process using the port (Windows)
netstat -ano | findstr :8080
taskkill /PID <PID> /F

# Or kill the process (Mac/Linux)
lsof -ti:8080 | xargs kill -9

Reset Onboarding

To see the onboarding screen again:

Press F12 → Console tab
Type: localStorage.clear() and press Enter
Refresh the page (F5)

Need More Help?

🐛 Open an Issue
📧 Email: nene171408@gmail.com

🤝 Contributing

We love contributions! FitQuest is built by developers like you.

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Contribution Guidelines

Follow the existing code style and architecture patterns
Write tests for new features
Update documentation as needed
Keep commits atomic and well-described
Be respectful and constructive in discussions

Areas for Contribution

🐛 Bug fixes
✨ New features
📝 Documentation improvements
🌍 Translations
🎨 UI/UX enhancements
🧪 Test coverage

📊 Development Progress

Phase 1: Foundation (✅ Complete)

Project setup and architecture
UI design system
Navigation structure

Phase 2: Core Features (🚧 In Progress - 70%)

Phase 3: Firebase Integration (📅 Planned)

Firestore integration
Cloud storage setup
Real-time sync
Cloud functions

Phase 4: Advanced Features (📅 Planned)

Leaderboards
Social features
Notifications
Analytics

Phase 5: Testing & Quality (📅 Planned)

Unit test coverage (80%+)
Integration tests
Performance optimization
Accessibility audit

Phase 6: Production (📅 Planned)

Beta testing
App Store submission
Play Store submission
Web deployment

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Nicolette Mashaba

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

👤 Author

Nicolette Mashaba

Passionate Flutter developer building engaging mobile experiences

🙏 Acknowledgments

Special thanks to:

💙 Flutter Team - For the amazing cross-platform framework
🔥 Firebase Team - For robust backend infrastructure
🎓 Jediah Codes - For the comprehensive learning path at jediah.dev
🌟 Open Source Community - For invaluable packages and support
🎨 Design Inspiration - Duolingo, Habitica, and Forest App

Key Dependencies

Special thanks to these amazing packages:

firebase_core & firebase_auth - Backend services
flutter_bloc - State management
rive - Beautiful animations
fl_chart - Data visualization
hive - Local storage
confetti - Celebration animations

📞 Support & Community

Get Help

📖 Documentation - Comprehensive guides
❓ Stack Overflow - Technical questions
🐛 Issue Tracker - Report bugs

Stay Updated

⭐ Star this repo to show support
👀 Watch for updates
📧 Subscribe to our newsletter (coming soon)

🌱 Grow Your Wellness Journey with FitQuest

Made with ❤️ and Flutter

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 108 Commits
android		android
android_old_broken		android_old_broken
assets		assets
docs		docs
lib		lib
linux		linux
macos		macos
test		test
tools		tools
web		web
windows		windows
.gitattributes		.gitattributes
.gitignore		.gitignore
.metadata		.metadata
LICENSE		LICENSE
README.md		README.md
analysis_options.yaml		analysis_options.yaml
build.yaml		build.yaml
devtools_options.yaml		devtools_options.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

Folders and files

Latest commit

History

Repository files navigation

🌱 FitQuest

🎯 Project Overview

💪 How It Works

🌳 Plant Evolution Stages

✨ Key Features

🎮 Core Gameplay

📊 Tracking & Analytics

🏆 Social & Competition

🔧 User Experience

🛠️ Tech Stack

Frontend

Backend & Services

Architecture & Patterns

📋 Prerequisites

Verify Installation

🚀 Getting Started

1️⃣ Clone the Repository

2️⃣ Install Dependencies

3️⃣ Set up Firebase

a. Create a Firebase Project

b. Enable Required Services

c. Add Your App to Firebase

d. Configure FlutterFire CLI

4️⃣ Run the App

5️⃣ Build for Production

📁 Project Structure

🧪 Testing

Run All Tests

Run Tests with Coverage

Run Integration Tests

Run Specific Test File

Test Categories

📚 Documentation

🗺️ Roadmap

✅ Completed

🚧 In Progress (Q1 2025)

📅 Planned (Q2 2025)

🔮 Future (Q3 2025+)

🐛 Troubleshooting

Common Issues

1. Blank Screen on Web

2. Firebase Configuration Errors

3. Firestore Index Errors

4. Build Errors After Updating Dependencies

5. Port Already in Use (Web)

Reset Onboarding

Need More Help?

🤝 Contributing

How to Contribute

Contribution Guidelines

Areas for Contribution

📊 Development Progress

Phase 1: Foundation (✅ Complete)

Phase 2: Core Features (🚧 In Progress - 70%)

Phase 3: Firebase Integration (📅 Planned)

Phase 4: Advanced Features (📅 Planned)

Phase 5: Testing & Quality (📅 Planned)

Phase 6: Production (📅 Planned)

📄 License

👤 Author

Nicolette Mashaba

🙏 Acknowledgments

Key Dependencies

📞 Support & Community

Get Help

Stay Updated

🌱 Grow Your Wellness Journey with FitQuest

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages