Mobile App Setup

This guide covers setting up the development environment, configuring the app, and building for iOS and Android.

Prerequisites

Before starting, ensure you have the required tools installed:

Flutter SDK 3.27.0 or later
Dart SDK 3.0.0 or later
Android Studio (for Android builds)
Xcode (for iOS builds, macOS only)
Git for version control

Install Flutter

Follow the official Flutter installation guide for your platform:

macOS
Linux
Windows

# Install Flutter using Homebrew
brew install --cask flutter

# Or download and extract manually
cd ~/development
unzip ~/Downloads/flutter_macos_*.zip
export PATH="$PATH:`pwd`/flutter/bin"

# Run doctor to check dependencies
flutter doctor

# Download Flutter
cd ~/development
wget https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_*-stable.tar.xz
tar xf flutter_linux_*-stable.tar.xz

# Add to PATH
export PATH="$PATH:`pwd`/flutter/bin"

# Run doctor
flutter doctor

# Download Flutter from https://flutter.dev/docs/get-started/install/windows
# Extract to C:\src\flutter

# Add to PATH environment variable
# Then run:
flutter doctor

Verify Installation

flutter doctor -v

Ensure all required dependencies are installed. You should see checkmarks for:

Flutter (Channel stable)
Android toolchain
Xcode (macOS only)
VS Code or Android Studio

Clone the Repository

Clone the Sure repository and navigate to the mobile directory:

git clone https://github.com/we-promise/sure.git
cd sure/mobile

Development Setup

Install Dependencies

Install all Flutter packages defined in pubspec.yaml:

flutter pub get

For iOS development, also install CocoaPods dependencies:

cd ios
pod install
cd ..

Generate App Icons

Generate platform-specific app icons from the source image:

flutter pub run flutter_launcher_icons

This creates icons for iOS and Android based on assets/icon/app_icon.png.

This step is required before building the app locally.

Configure Backend URL

Edit lib/services/api_config.dart to point to your Sure backend server:

Android Emulator
iOS Simulator
Physical Device
Production

// lib/services/api_config.dart
static const String _defaultBaseUrl = 'http://10.0.2.2:3000';

The address 10.0.2.2 is a special alias to the host machine’s localhost.

// lib/services/api_config.dart
static const String _defaultBaseUrl = 'http://localhost:3000';

// lib/services/api_config.dart
static const String _defaultBaseUrl = 'http://YOUR_COMPUTER_IP:3000';

Replace YOUR_COMPUTER_IP with your computer’s local network IP address.

// lib/services/api_config.dart
static const String _defaultBaseUrl = 'https://your-sure-server.com';

Run the App

Start the app in development mode:

Android
iOS
Web (Dev)

# List available devices
flutter devices

# Run on connected Android device/emulator
flutter run -d android

# List available simulators
flutter devices

# Run on specific simulator
flutter run -d "iPhone 15 Pro"

# Or use device UDID
flutter run -d <simulator-device-UDID>

# Run in Chrome (for quick testing only)
flutter run -d chrome

Web platform is for development only and not officially supported for production.

Building for Release

Android Builds

Build APK

Generate an APK file for direct installation:

flutter build apk --release

Output location: build/app/outputs/flutter-apk/app-release.apk

Build App Bundle (Google Play)

Generate an App Bundle for Google Play Store:

flutter build appbundle --release

Output location: build/app/outputs/bundle/release/app-release.aab

App Bundles are optimized for Play Store distribution and result in smaller download sizes.

iOS Builds

Install CocoaPods Dependencies

cd ios
pod install
cd ..

Build iOS Release

flutter build ios --release

This creates an unsigned build. For App Store distribution, you’ll need to sign the build in Xcode.

Sign and Archive (Optional)

Open the project in Xcode:

open ios/Runner.xcworkspace

Then:

Select your development team in Xcode
Configure signing certificates
Product → Archive
Upload to App Store Connect or export IPA

For detailed iOS build instructions and troubleshooting, see mobile/docs/iOS_BUILD.md in the repository.

CI/CD Configuration

The mobile app includes automated builds via GitHub Actions:

Workflow Triggers

Push to main branch (when Flutter files change)
Pull requests to main branch
Tags matching mobile-release-* (triggers TestFlight upload)

Build Pipeline

The workflow (.github/workflows/flutter-build.yml) performs:

Code Analysis: flutter analyze
Tests: flutter test
Android Builds:
- Release APK
- Release App Bundle (AAB)
iOS Build: Unsigned release build
Artifact Upload: Build outputs uploaded as artifacts

TestFlight Distribution

When a mobile release is tagged, .github/workflows/ios-testflight.yml runs to:

Build signed iOS release
Archive and export IPA
Upload to App Store Connect
Submit for TestFlight beta testing

Required secrets for TestFlight: APPLE_ID, APP_STORE_CONNECT_API_KEY, MATCH_PASSWORD, etc. See mobile/docs/iOS_TESTFLIGHT.md for complete setup.

Download Build Artifacts

After a successful CI run:

Go to the Actions tab on GitHub
Select the workflow run
Download artifacts:
- app-release-apk - Android APK
- app-release-aab - Android App Bundle
- ios-build-unsigned - iOS app (requires signing)

Development Environment

Recommended IDE Setup

Android Studio

Full Flutter support via plugin
Built-in Android emulator
Device manager and debugging tools
Install Flutter and Dart plugins

VS Code

Lightweight and fast
Excellent Flutter extension
Integrated terminal and debugging
Install Flutter and Dart extensions

Enable Hot Reload

When running in debug mode, use hot reload to see changes instantly:

Press r in the terminal to hot reload
Press R to hot restart
Press h for help

Debugging Tips

View Logs

# View all logs
flutter logs

# Android logs only
adb logcat

# iOS logs (device)
idevicesyslog

Clear App Data

Android
iOS Simulator

adb shell pm clear com.sure.sure_mobile

Long press the app icon → Remove App → ReinstallOr delete and rebuild:

flutter clean
flutter pub get
flutter run

Network Debugging

To inspect API requests:

Use Flutter DevTools: flutter pub global run devtools
Enable network logging in lib/services/*_service.dart
Use Android Studio’s Network Profiler

Configuration Files

pubspec.yaml

Defines app metadata and dependencies:

name: sure_mobile
description: A mobile app for Sure personal finance management
version: 0.6.9+1

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: '>=3.27.0'

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  provider: ^6.1.1
  shared_preferences: ^2.2.2
  flutter_secure_storage: ^10.0.0
  intl: ^0.18.1
  sqflite: ^2.4.2
  # ... more dependencies

API Configuration

lib/services/api_config.dart manages backend connectivity:

class ApiConfig {
  static const String _defaultBaseUrl = 'https://demo.sure.am';
  static const Duration connectTimeout = Duration(seconds: 30);
  static const Duration receiveTimeout = Duration(seconds: 30);
  
  static Future<bool> initialize() async {
    // Loads saved backend URL from storage
  }
}

Troubleshooting

Common Issues

Flutter command not found

Add Flutter to your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:/path/to/flutter/bin"

Then reload your shell or run source ~/.bashrc.

CocoaPods installation fails (iOS)

Update CocoaPods:

sudo gem install cocoapods
pod repo update

Clear cache and retry:

cd ios
rm -rf Pods Podfile.lock
pod install

Android build fails with Gradle errors

Clean and rebuild:

flutter clean
cd android
./gradlew clean
cd ..
flutter pub get
flutter build apk

Cannot connect to backend on Android emulator

Ensure you’re using 10.0.2.2 instead of localhost:

// Correct for Android emulator
static const String _defaultBaseUrl = 'http://10.0.2.2:3000';

Verify your backend is running:

curl http://localhost:3000/sessions/new

App icon not showing

Regenerate icons:

flutter pub run flutter_launcher_icons
flutter clean
flutter run

Next Steps

Once your development environment is set up:

Review the Authentication Guide to understand the auth flow
Explore the codebase structure in lib/
Check existing screens in lib/screens/
Review API services in lib/services/
Customize the app for your needs

Get Started

Self-Hosting

Core Features

Integrations

Mobile App

Mobile App Setup

Prerequisites

Install Flutter

Verify Installation

Clone the Repository

Development Setup

Building for Release

Android Builds

iOS Builds

CI/CD Configuration

Workflow Triggers

Build Pipeline

TestFlight Distribution

Download Build Artifacts

Development Environment

Recommended IDE Setup

Android Studio

VS Code

Enable Hot Reload

Debugging Tips

View Logs

Clear App Data

Network Debugging

Configuration Files

pubspec.yaml

API Configuration

Troubleshooting

Common Issues

Next Steps

Additional Resources

Build docs developers (and LLMs) love

Get Started

Self-Hosting

Core Features

Integrations

Mobile App

​Prerequisites

​Install Flutter

​Verify Installation

​Clone the Repository

​Development Setup

​Building for Release

​Android Builds

​iOS Builds

​CI/CD Configuration

​Workflow Triggers

​Build Pipeline

​TestFlight Distribution

​Download Build Artifacts

​Development Environment

​Recommended IDE Setup

Android Studio

VS Code

​Enable Hot Reload

​Debugging Tips

​View Logs

​Clear App Data

​Network Debugging

​Configuration Files

​pubspec.yaml

​API Configuration

​Troubleshooting

​Common Issues

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Install Flutter

Verify Installation

Clone the Repository

Development Setup

Building for Release

Android Builds

iOS Builds

CI/CD Configuration

Workflow Triggers

Build Pipeline

TestFlight Distribution

Download Build Artifacts

Development Environment

Recommended IDE Setup

Enable Hot Reload

Debugging Tips

View Logs

Clear App Data

Network Debugging

Configuration Files

pubspec.yaml

API Configuration

Troubleshooting

Common Issues

Next Steps

Additional Resources