SoberPath - Free & Open Source Sobriety Tracking App

Break bad habits, build new ones, reach new milestones

A free and open-source alternative to "I Am Sober"

Made in Serbia ❤️

🌟 Features

Core Functionality

Multiple Addiction Trackers: Track sobriety from alcohol, smoking, drugs, gambling, gaming, social media, junk food, and more
Custom Trackers: Add your own custom addictions to track
Real-Time Countdown: See your progress in days, hours, minutes, and seconds
Milestone System: Celebrate achievements at predefined milestones (1 day, 1 week, 1 month, 1 year, etc.)
Savings Calculator: Track money saved by staying sober with customizable pricing and currency
Daily Motivational Quotes: Get inspired with daily quotes (powered by ZenQuotes API)
Optional Daily Pledge: Optional feature to reinforce commitment (can be enabled/disabled in settings)

User Experience

📱 Mobile-First Design: Beautiful, native mobile experience
🎨 Modern UI: Clean, gradient-based design with intuitive navigation
📊 Statistics Dashboard: Comprehensive stats showing total progress and savings
🎯 Progress Visualization: Clear visual representation of achievements
💾 Local Storage: All data stored locally on your device - no account needed
🔒 Privacy-Focused: No data collection, no tracking, no ads

🛠️ Tech Stack

Frontend: Expo (React Native) with TypeScript
Navigation: Expo Router (file-based routing)
Storage: AsyncStorage (local device storage)
UI Components: React Native core components + Expo Vector Icons
Date Handling: date-fns
Charts: react-native-gifted-charts
License: GPL-3.0

🚀 Getting Started - Complete Guide

Prerequisites (Required Software)

Before you can build and run the SoberPath app, you need to install these tools:

For Ubuntu/Debian Linux Users:

# Update package list
sudo apt update

# Install Node.js (v20 LTS recommended)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Git
sudo apt-get install -y git

# Install build essentials (required for some dependencies)
sudo apt-get install -y build-essential

# Verify installations
node --version
npm --version
git --version

For Windows/Mac Users:

Node.js (v18 or higher recommended)
- Download from: https://nodejs.org/
- Choose the LTS (Long Term Support) version
- Verify installation: node --version and npm --version
Git (for downloading the code)
- Download from: https://git-scm.com/
- Verify installation: git --version
Code Editor (recommended)
- Visual Studio Code: https://code.visualstudio.com/
- Or any editor you prefer

Mobile Testing Options (All Platforms):

Option A: Install Expo Go app on your phone (easiest - recommended)
- iOS: App Store → Search "Expo Go"
- Android: Google Play → Search "Expo Go"
Option B: Android Studio (for Android emulator)
Option C: Xcode (for iOS simulator - Mac only)

📱 Development Setup (Step by Step)

Step 1: Download the Code

# Open terminal/command prompt and run:
git clone https://github.com/sectorfive/soberpath.git
cd soberpath

Step 2: Install Dependencies

# Navigate to the frontend folder
cd frontend

# Install all required packages
npm install
# OR if you prefer yarn:
yarn install

Step 3: Start Development Server

# Start the Expo development server
npm start
# OR
yarn start
# OR
npx expo start

Step 4: Test on Your Device

After running npm start, you'll see:

A QR code in your terminal
A web interface at http://localhost:8081 (or similar port)
A list of available commands in the terminal

🎯 Testing on Physical Phone (Recommended for best experience):

Install Expo Go App
- iOS: Open App Store → Search "Expo Go" → Install
- Android: Open Google Play Store → Search "Expo Go" → Install
Connect to the Same WiFi Network
- Make sure your phone and computer are on the same WiFi network
- This is crucial for the connection to work
Scan the QR Code
- iOS: Open the Camera app → Point at the QR code in terminal → Tap the notification
- Android: Open Expo Go app → Tap "Scan QR Code" → Scan the QR code from terminal
Wait for App to Load
- First load may take 1-2 minutes as it bundles the JavaScript
- Subsequent loads are much faster (hot reload)
- You'll see "SoberPath" app launch on your phone

🖥️ Testing in Web Browser:

Press w in the terminal to open web version
Or click "Open in web browser" in the Expo DevTools
Note: Some mobile features may not work in browser

📱 Testing in Android Emulator:

Press a in the terminal
Requires Android Studio with emulator setup

🍎 Testing in iOS Simulator (Mac only):

Press i in the terminal
Requires Xcode with simulator setup

🔧 Troubleshooting Testing:

# If QR code doesn't work, try tunnel mode:
npx expo start --tunnel

# If you see connection errors:
# 1. Check both devices are on same WiFi
# 2. Disable VPN if active
# 3. Check firewall settings

# Clear cache if seeing old code:
npx expo start -c

🏗️ Building for Production (.APK/.IPA Files)

Option 1: Expo Application Services (EAS) - Recommended

Install EAS CLI

npm install -g eas-cli

Create Expo Account (if you don't have one)

eas login

Configure the project

eas build:configure

Build for Android (.APK)

# For development build (easier to install)
eas build --platform android --profile development

# For production build (for Play Store)
eas build --platform android --profile production

Build for iOS (.IPA) (Mac required)

# You need Apple Developer account ($99/year)
eas build --platform ios --profile production

Download your built app
- Go to https://expo.dev/accounts/[your-username]/projects/soberpath/builds
- Download the .apk (Android) or .ipa (iOS) file

Option 2: Local Build (Advanced Users)

For Android (.APK):

# Prerequisites: Android Studio installed
npx expo run:android --variant release

For iOS (.IPA): (Mac only)

# Prerequisites: Xcode installed, Apple Developer account
npx expo run:ios --configuration Release

📦 Distribution Options

Android Distribution:

Direct APK Installation
- Enable "Unknown Sources" in Android Settings
- Transfer .apk file to Android device
- Tap the file to install
Google Play Store (requires Google Play Console account)
- Upload the production .aab file to Google Play Console
- Complete store listing and compliance forms

iOS Distribution:

TestFlight (internal testing)
- Upload .ipa to App Store Connect
- Invite testers via email
App Store (public release)
- Submit app for App Store review
- Requires Apple Developer Program membership ($99/year)

🛠️ Development Environment Setup

Recommended VS Code Extensions:

# Install these extensions for better development experience:
- React Native Tools
- ES7+ React/Redux/React-Native snippets
- Expo Tools
- TypeScript Importer

Environment Variables Setup:

The app uses local storage by default, but you can configure additional settings:

Create .env file in the frontend folder:

# Optional: Add custom configuration
EXPO_PUBLIC_APP_VARIANT=development

🐛 Troubleshooting Common Issues

Issue: "Metro bundler not starting"

# Solution: Clear cache and restart
npx expo start -c

Issue: "Could not connect to development server"

# Solution: Make sure you're on the same WiFi network
# Or try tunnel mode:
npx expo start --tunnel

Issue: "Android build fails"

# Solution: Clear gradle cache
cd android
./gradlew clean
cd ..

Issue: "iOS build fails"

# Solution: Clear derived data (Mac only)
rm -rf ~/Library/Developer/Xcode/DerivedData

📱 Testing on Different Devices

Physical Device Testing:

Android: Use Expo Go app or install .apk directly
iOS: Use Expo Go app or TestFlight for .ipa

Emulator/Simulator Testing:

Android Emulator: Android Studio → AVD Manager
iOS Simulator: Xcode → Window → Devices and Simulators

🔄 Making Changes and Updates

Make your code changes in the frontend folder
Test thoroughly on development server
Build new version when ready
Update version number in app.json
Distribute updated build

📋 Project Structure

soberpath/
├── frontend/                 # Main app folder
│   ├── app/                 # App screens (Expo Router)
│   │   ├── (tabs)/         # Tab navigation screens
│   │   ├── _layout.tsx     # Root layout
│   │   └── index.tsx       # Entry point
│   ├── assets/             # Images, fonts, etc.
│   │   └── images/         # App icons and images
│   │       ├── icon.png           # Main app icon (1024x1024)
│   │       ├── adaptive-icon.png  # Android adaptive icon (1024x1024)
│   │       └── favicon.png        # Web favicon (48x48 or larger)
│   ├── utils/              # Helper functions
│   ├── types/              # TypeScript definitions
│   ├── app.json           # Expo configuration
│   └── package.json       # Dependencies
├── README.md              # This file
└── LICENSE               # GPL-3.0 License

🎨 Customizing App Icons & Branding

Want to personalize SoberPath with your own icons and branding? Here's how:

App Icons to Replace:

icon.png (frontend/assets/images/icon.png)
- Size: 1024x1024 pixels
- Format: PNG with transparency
- Usage: Main app icon for iOS, Android, and Expo Go
- Design tip: Use a simple, recognizable symbol with padding around edges
adaptive-icon.png (frontend/assets/images/adaptive-icon.png)
- Size: 1024x1024 pixels
- Format: PNG with transparency
- Usage: Android adaptive icon (may be cropped into circle/square)
- Design tip: Keep important content in center 66% of canvas
- Background color: Edit in app.json → android.adaptiveIcon.backgroundColor
favicon.png (frontend/assets/images/favicon.png)
- Size: 48x48 pixels (or larger, will be scaled down)
- Format: PNG
- Usage: Web browser tab icon
- Design tip: Should be recognizable at small sizes

Quick Icon Replacement Steps:

# Navigate to assets folder
cd frontend/assets/images

# Backup original icons (optional)
mkdir ../original_icons
cp icon.png adaptive-icon.png favicon.png ../original_icons/

# Replace with your icons (make sure they're named correctly)
# Copy your new icon files to this directory with the same names

Update App Metadata:

Edit frontend/app.json to customize:

{
  "expo": {
    "name": "Your App Name",
    "slug": "your-app-slug",
    "description": "Your app description",
    "android": {
      "adaptiveIcon": {
        "backgroundColor": "#YourColor"  // Hex color for Android icon background
      }
    }
  }
}

Icon Design Resources:

Free Icon Makers:
- Canva (https://canva.com) - Easy drag-and-drop
- GIMP (https://gimp.org) - Free Photoshop alternative
- Figma (https://figma.com) - Professional design tool
Icon Guidelines:
- iOS: https://developer.apple.com/design/human-interface-guidelines/app-icons
- Android: https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive

After Replacing Icons:

# Clear cache and restart
npx expo start -c

# For production builds
eas build --platform android --profile production

This guide should help you get started with building and maintaining the SoberPath app! 🎉

📱 How to Use

Adding a Tracker

Tap the "Add Tracker" button on the home screen or trackers tab
Select an addiction type from the list (or choose "Custom")
Set your sober start date
(Optional) Add pricing information for savings tracking
Tap "Create Tracker"

Viewing Progress

Home Tab: See real-time countdown for all active trackers
Trackers Tab: Manage all your trackers (edit, pause, or delete)
Stats Tab: View detailed statistics, milestones, and total savings
Settings Tab: Configure app preferences and view app information

Savings Calculator

Enter the price per unit (e.g., $10 per drink)
Enter your typical daily consumption (e.g., 2 drinks per day)
Choose your currency symbol (e.g., $, €, £)
The app automatically calculates your total savings

🎯 Milestones

The app includes 15 predefined milestones:

1 Day, 3 Days, 1 Week, 2 Weeks, 3 Weeks
1 Month, 2 Months, 3 Months, 6 Months, 9 Months
1 Year, 2 Years, 3 Years, 5 Years, 10 Years

📊 Data & Privacy

100% Local Storage: All your data is stored only on your device
No Account Required: No sign-up, no login, no personal information collected
No Analytics: We don't track your usage or behavior
No Ads: Completely ad-free experience
Open Source: Full transparency - inspect the code yourself

🤝 Contributing

We welcome contributions! This is a free and open-source project.

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

Ideas for Contributions

🌐 Localization/translations
🎨 UI/UX improvements
🔔 Push notifications for milestones
📊 More chart types and visualizations
📸 Add photos/journal entries to trackers
☁️ Optional cloud backup
📝 Export data to CSV/JSON

📝 License & Legal Information

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

This means:

✅ You can freely use, modify, and distribute this software
✅ You can use it for commercial purposes
⚠️ If you distribute modified versions, you must also make them open source under GPL-3.0
⚠️ You must include the original copyright and license notices

See the LICENSE file for the full license text.

🇷🇸 Serbian Law Compliance & Legal Information

This open-source software is subject to Serbian law (including the Law on Copyright and Related Rights, Official Gazette of RS, No. 104/2009) and is provided "AS IS" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement.

About This Software:

This application is made by a single person and is not affiliated with any company or legal entity
The software is distributed freely under the GPL-3.0 license
In accordance with Serbian consumer protection law, this software is provided free of charge with no warranties or guarantees

Important Disclaimers:

⚠️ Medical Disclaimer: This application is NOT a replacement for professional addiction treatment. Please consult with healthcare providers for serious addiction issues.
⚠️ No Liability: The developer is not responsible for any damages to your device, data loss, or any other consequences from using this application.
⚠️ No Warranty: The software is provided without any warranty or guarantee of functionality.
⚠️ Use at Your Own Risk: By using this application, you acknowledge and accept all risks associated with its use.

🚀 Roadmap

❤️ Support

If you find this app helpful, please:

⭐ Star this repository
🐛 Report bugs and issues
💡 Suggest new features
👥 Share with others who might benefit

📧 Contact