Wellbeing Mapper

What is Wellbeing Mapper?

Wellbeing Mapper is a privacy-focused mobile application that lets you map your mental wellbeing in environmental & climate context.

Available Modes

This application offers three modes of use:

• 🔒 Private Mode: Use the app for personal wellbeing tracking - all data stays on your device
• 🔬 Research Mode: Participate in the Planet4Health study in Gauteng, South Africa with secure data sharing
• 🧪 App Testing Mode: Test all research features safely - no real research data is collected

About the Research

The app enables participants to map the routes they take and places where they spend time while tracking their mental wellbeing through surveys and digital diary entries. Research participants can securely share this information with researchers studying how environmental and climate factors impact mental wellbeing.

This application is part of a case study in the Planet4Health project, a Horizon Europe research initiative focused on translating science into policy for planetary health. The case study specifically addresses "Mental wellbeing in environmental & climate context" - an emerging field that recognizes how environmental and climate changes contribute to rising mental health and psychosocial issues.

About the Planet4Health Case Study

Traditional studies on environmental and climate change impacts have predominantly focused on physical health. However, these changes also contribute to a range of mental health disorders from emotional distress to the exacerbation of existing mental health conditions, often referred to as climate-related psychological distress.

This case study aims to:

• Collect and analyze mental wellbeing data alongside environmental data
• Develop comprehensive understanding of mental health impacts from environmental factors
• Create integrated risk monitoring systems
• Map environmental hotspots affecting mental health
• Provide solutions for better preparedness and response capacity

Prerequisites

Important: This project requires Flutter 3.27.1 with Dart 3.6.0 specifically. The app will not compile with other versions due to dependency constraints.

Using FVM (Recommended)

# Install FVM
dart pub global activate fvm

# Use the correct Flutter version
fvm use 3.27.1

# Verify version
fvm flutter --version

Without FVM

Ensure you have Flutter 3.27.1 installed:

flutter --version
# Should show: Flutter 3.27.1 • Dart 3.6.0

Building from source

If you've just cloned this repo and want to build it on your own machine, follow docs/CONTRIBUTOR_SETUP.md. It covers:

• toolchain versions (Flutter 3.27.1, Xcode 15+, etc.)
• one-time per-clone setup (flutter pub get, pod install, ./sync-version.sh)
• which files are gitignored and need to be created locally
• how to point a build at a local server with --dart-define=SERVER_BASE_URL=...
• how to optionally develop open-background-locator in parallel (it is fetched from GitHub by default)
• the (optional) local wellbeing-mapper-server

Safety note for collaborators: by default the app's research-server URL is a placeholder, and every upload path refuses to send data when the placeholder is in use. You must explicitly pass --dart-define=SERVER_BASE_URL=... to direct uploads anywhere. This app should never post to the Gauteng Wellbeing Mapper production server.

Direct Android phone testing (USB)

For quick local testing on a real Android phone (without store release flow), use:

./scripts/deploy-android-phone.sh

Defaults:

• flavor: production
• ABI: arm64-v8a

Examples:

./scripts/deploy-android-phone.sh production arm64-v8a
./scripts/deploy-android-phone.sh beta armeabi-v7a
./scripts/deploy-android-phone.sh production arm64-v8a --serial RZCW90B03FV
./scripts/deploy-android-phone.sh production arm64-v8a --reset-keys

If you hit device unauthorized, the script will pause and prompt you to:

1. keep phone unlocked,
2. switch USB mode to File transfer,
3. accept the "Allow USB debugging" prompt.

If the phone prompt never appears, run once with --reset-keys and re-accept fingerprint authorization.

How to contribute

Do you want to contribute?

Feel free to fork our repository, create a new branch, make your changes and submit a pull request(*). We'll review it as soon as possible and merge it.

(*)Before opening the pull request, please run the commands fvm flutter analyze and fvm flutter test locally (or flutter analyze and flutter test if not using FVM) to ensure that your PR passes all the tests successfully in our continuous integration (CI) workflow.

It would be awesome if you assign yourself to an existing task or you open a new issue in Github Issues, to keep other contributors informed on what you're working on.

If this project is useful for you, please consider starring this repository and giving us 5 stars on the app stores to give us more visibility.

Contributors

• Otis Johnson
  • github.com/StuffJoy
• Pablo Galve Millán
  • github.com/pablogalve
  • linkedin.com/in/pablogalve/
• John R.B. Palmer
  • github.com/johnpalmer

Documentation

For Users

• User Guide - Complete guide for using the app
• Getting Started - How to choose modes and begin tracking
• Privacy Guide - Understanding data privacy and security
• Screenshots Gallery - Visual guide showing app interface across devices

For Developers

• Developer Guide - Technical documentation and architecture
• App Mode System - Understanding private vs. research modes

Screenshots

Mobile Interface (iPhone)

Tablet Interface (7-inch Landscape)

Tablet Interface (10-inch Landscape)

Features

Core Features

• 🔒 Private Mode: Track your mental wellbeing privately on your device
• 🔬 Research Mode: Participate in the Planet4Health study with secure data sharing
• 🧪 App Testing Mode: Experience research features safely with no data collection
• 📍 Location Tracking: Background GPS tracking with full user control
• 📝 Wellbeing Surveys: Quick 2-3 minute mental wellbeing assessments
• 🔔 Smart Notifications: Bi-weekly survey reminders with customizable intervals
• ** End-to-End Encryption**: Military-grade RSA+AES encryption for research data
• 📊 Research Data Upload: Secure bi-weekly uploads to research servers
• 🌍 Multi-Site Support: Barcelona, Spain and Gauteng, South Africa studies
• 📋 Consent Management: Full research consent and information sheets
• 🎯 Climate-Health Research: Contribute to understanding climate psychological impacts
• 🔒 Privacy-First Design: Complete control over your data
• 🎨 Intuitive Interface: Easy-to-use design with clear mode explanations

App Modes

Private Mode 🔒

Use Wellbeing Mapper for personal insight:

• ✅ Track your mental wellbeing privately
• ✅ All data stays on your device
• ✅ No data sharing or uploads
• ✅ Personal insights and patterns

Research Mode 🔬

Participate in the Planet4Health study:

• 🔬 Real study participation in Gauteng, South Africa
• 📋 Participant codes and consent processes
• 🔐 Encrypted data sharing with research teams
• 📊 Contribute to climate-mental health research

App Testing Mode 🧪

Experience research features safely:

• ✅ Test all app features without data collection
• ✅ Experience research workflows safely
• ✅ Provide feedback on user experience
• ✅ All testing data stays on your device

Download

Visit the app stores to download Wellbeing Mapper:

• Google Play (Android)

• Apple App Store (iOS)

• Github Releases (Android) For more information about the Planet4Health project, please visit the Planet4Health website and learn about the Mental wellbeing in environmental & climate context case study.

• Google Play (Android).

• Apple Store (iOS) (Coming soon)

• Github Releases (Android).

About Planet4Health

Planet4Health is a Horizon Europe research project focused on "Translating Science into Policy: A Multisectoral Approach to Adaptation and Mitigation of Adverse Effects of Vector-Borne Diseases, Environmental Pollution and Climate Change on Planetary Health." The project is part of the Planetary Health Cluster, which includes five Horizon Europe projects working together to address climate change and health challenges.

Funding: This project is funded by the European Union under the Horizon Europe programme. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Health and Digital Executive Agency (HADEA).

Development

Version Synchronization

Important: Android builds use local.properties to override pubspec.yaml version information. To ensure correct versions:

# Sync local.properties with pubspec.yaml version
./sync-version.sh

# Then build with correct version
flutter build apk --release --flavor production

CI/CD Fix: The GitHub Actions workflows now automatically regenerate local.properties with correct version information before builds to prevent version mismatches between releases.

Common Issues

• APK Upgrade Fails: Ensure version codes are incrementing. Use ./sync-version.sh to sync versions.
• Version Mismatch: Android builds may use cached local.properties. Run ./sync-version.sh to fix.

License

This repository contains the source code development version of Wellbeing Mapper, developed as part of the Planet4Health project case study on mental wellbeing in environmental & climate context.

This project is licensed under the GNU GENERAL PUBLIC LICENSE

Copyright 2011-2020 John R.B. Palmer Copyright 2021-2023 John R.B. Palmer and Pablo Galve Millán Copyright 2021-2023 John R.B. Palmer, Pablo Galve Millán, and Otis Johnson

Wellbeing Mapper is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Wellbeing Mapper is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses.