mobile-app-guide.md

Stellar-Save Mobile App User Guide

Welcome to the Stellar-Save mobile app! This guide covers everything you need to know about using Stellar-Save on your iOS or Android device.

Getting Started

Installation

iOS (iPhone/iPad)

1. Open the App Store
2. Search for "Stellar-Save"
3. Tap "Get" and authenticate with Face ID/Touch ID/password
4. Wait for installation to complete
5. Tap "Open" or find the app on your home screen

Android

1. Open Google Play Store
2. Search for "Stellar-Save"
3. Tap "Install"
4. Wait for installation to complete
5. Tap "Open" or find the app in your app drawer

System Requirements

iOS

• iOS 14.0 or later
• iPhone 6s or newer
• iPad (5th generation) or newer
• 50 MB free storage

Android

• Android 8.0 (Oreo) or later
• 2 GB RAM minimum
• 100 MB free storage

First Launch Setup

1. Welcome Screen: Tap "Get Started"
2. Network Selection: Choose Testnet (for learning) or Mainnet (for real savings)
3. Wallet Setup:
   • Create new wallet, or
   • Import existing wallet with seed phrase
4. Biometric Authentication: Enable Face ID/Touch ID/Fingerprint (recommended)
5. Notifications: Allow push notifications to stay updated on contributions and payouts
6. Tutorial: Complete the quick walkthrough (optional but recommended)

Mobile-Specific Features

Quick Actions (iOS)

Long-press the Stellar-Save app icon for quick shortcuts:

• View My Groups: Jump directly to your active groups
• Make Contribution: Quick access to contribute to due groups
• Check Balance: View your XLM balance instantly
• Scan QR Code: Join a group via QR code

Home Screen Widgets

iOS Widgets

• Small Widget: Shows next contribution due date and amount
• Medium Widget: Displays all active groups with status
• Large Widget: Full dashboard with contribution history

To add: Long-press home screen → Tap "+" → Search "Stellar-Save" → Select widget size

Android Widgets

• 1x1 Widget: Quick contribution button
• 2x2 Widget: Group overview with next payout
• 4x2 Widget: Full dashboard with recent activity

To add: Long-press home screen → Tap "Widgets" → Find "Stellar-Save" → Drag to home screen

Push Notifications

Stay informed with real-time alerts:

• Contribution Reminders: 24 hours before cycle deadline
• Payout Notifications: When you receive funds
• Group Updates: New members join or group status changes
• Cycle Completion: When all members have contributed
• Penalty Alerts: If penalties are applied (when enabled)

Managing Notifications

• iOS: Settings → Stellar-Save → Notifications
• Android: Settings → Apps → Stellar-Save → Notifications

Biometric Security

Protect your wallet with device biometrics:

• iOS: Face ID or Touch ID
• Android: Fingerprint or Face Unlock

Setup: App Settings → Security → Enable Biometric Authentication

When Required:

• Opening the app (optional)
• Making contributions
• Viewing seed phrase
• Changing security settings

Camera & QR Codes

Scanning QR Codes

1. Tap the scan icon (camera) in the top-right corner
2. Point camera at QR code
3. Auto-detects group IDs, wallet addresses, or payment requests
4. Confirm action

Sharing Your Group

1. Open your group
2. Tap "Share" icon
3. Select "QR Code"
4. Others can scan to join instantly

Permissions: Grant camera access when prompted (Settings → Stellar-Save → Camera)

Offline Mode

The app works partially offline with cached data.

Available Offline:

• View your groups and contribution history
• Check your wallet balance (last synced)
• Review group details and member lists
• Access settings and help documentation

Requires Connection:

• Making contributions
• Creating or joining groups
• Executing payouts
• Refreshing real-time data

Offline Indicator: Yellow banner at top shows "Offline Mode" when disconnected

Syncing: Data auto-syncs when connection is restored. Pull down to refresh manually.

Dark Mode

Automatically adapts to your device's appearance settings.

Manual Override: App Settings → Appearance → Light/Dark/Auto

Haptic Feedback

Subtle vibrations confirm actions:

• Contribution submitted
• Payout received
• Error occurred
• Button taps (optional)

Disable: App Settings → Accessibility → Haptic Feedback → Off

Gesture Controls

Navigation Gestures

iOS

• Swipe Right: Go back to previous screen
• Swipe Down: Dismiss modal/popup
• Pull Down: Refresh current view
• Long Press: Context menu (on groups, transactions)

Android

• Swipe Right/Back Button: Return to previous screen
• Swipe Down: Dismiss modal or refresh (context-dependent)
• Pull Down: Refresh current view
• Long Press: Context menu

Group Management Gestures

Swipe Actions on Group List

• Swipe Left: Quick actions menu
  • Contribute
  • View Details
  • Share Group
  • Leave Group (if allowed)
• Swipe Right: Mark as favorite (star icon appears)

Pull to Refresh: Update group status and contribution data

Transaction History Gestures

• Tap Transaction: View full details
• Long Press: Copy transaction ID or share
• Swipe Left: View on Stellar Explorer

Quick Contribution

Shortcut Gesture (when contribution is due):

1. Swipe left on group in "My Groups"
2. Tap "Contribute"
3. Authenticate with biometrics
4. Contribution submitted

Screen-by-Screen Guide

Home Dashboard

Top Section

• Total XLM balance
• Active groups count
• Next contribution due

Middle Section

• Active groups list with status indicators
• Contribution progress bars
• Upcoming payout notifications

Bottom Navigation

• Home (dashboard)
• Groups (browse/create)
• Activity (transaction history)
• Profile (settings/wallet)

Actions

• Tap group card → View group details
• Tap "+" button → Create or join group
• Tap notification bell → View all alerts

Group Details Screen

Header

• Group name/ID
• Status badge (Active/Pending/Complete)
• Share and settings icons

Info Cards

• Contribution amount
• Cycle duration
• Current cycle number
• Your payout position

Member List

• Profile pictures (if available)
• Contribution status (✓ or pending)
• Tap member → View contribution history

Action Buttons

• Contribute (if due)
• View History
• Invite Members

Contribution Screen

Amount Display

• Required contribution amount (large, centered)
• Your current balance
• Transaction fee estimate

Confirmation

• Review details
• Authenticate with biometrics
• Submit transaction

Success Screen

• Confirmation animation
• Transaction ID
• Share receipt option

Wallet Screen

Balance Overview

• Available XLM
• Reserved (in active groups)
• Total value

Actions

• Send XLM
• Receive (show QR code)
• Buy XLM (external link)
• Transaction history

Security

• View seed phrase (requires authentication)
• Change PIN/biometrics
• Export wallet

Settings Screen

Account

• Profile information
• Notification preferences
• Language selection

Security

• Biometric authentication
• Auto-lock timeout
• Seed phrase backup

App

• Network (Testnet/Mainnet)
• Appearance (Light/Dark)
• Haptic feedback
• Clear cache

Support

• Help & FAQ
• Contact support
• App version

Mobile Troubleshooting

Connection Issues

Problem: "Unable to connect to Stellar network"

Solutions:

1. Check internet connection (WiFi or mobile data)
2. Toggle airplane mode on/off
3. Switch between WiFi and mobile data
4. Check Stellar network status at status.stellar.org
5. Try different network (Settings → Network → Switch RPC endpoint)

Problem: "Transaction timeout"

Solutions:

1. Ensure stable internet connection
2. Increase transaction timeout (Settings → Advanced → Timeout)
3. Retry transaction
4. Check Stellar network congestion

Wallet Issues

Problem: "Insufficient balance"

Solutions:

1. Check your XLM balance (Wallet tab)
2. Ensure you have enough for contribution + fees (~0.00001 XLM fee)
3. Add more XLM to your wallet
4. Check if funds are reserved in other groups

Problem: "Cannot access wallet"

Solutions:

1. Verify biometric authentication is working
2. Use PIN as fallback (tap "Use PIN" on auth screen)
3. Restart the app
4. Reinstall app and restore with seed phrase

Problem: "Lost seed phrase"

Solutions:

• If you still have app access: Settings → Security → View Seed Phrase → Write it down
• If app is deleted: Seed phrase cannot be recovered. Funds are lost.
• Prevention: Always backup seed phrase securely

App Performance Issues

Problem: App is slow or laggy

Solutions:

1. Close and reopen the app
2. Clear app cache (Settings → Clear Cache)
3. Free up device storage (need 100+ MB free)
4. Update to latest app version
5. Restart your device
6. Reinstall the app (backup seed phrase first!)

Problem: App crashes on launch

Solutions:

1. Force close and reopen
2. Restart device
3. Check for app updates
4. Reinstall app (backup seed phrase first!)
5. Check system requirements (iOS 14+/Android 8+)

Problem: High battery drain

Solutions:

1. Disable background refresh (iOS: Settings → Stellar-Save → Background App Refresh)
2. Reduce notification frequency
3. Enable dark mode
4. Close app when not in use

Notification Issues

Problem: Not receiving notifications

Solutions:

1. Check notification permissions (Device Settings → Stellar-Save → Notifications → Allow)
2. Enable specific notification types (App Settings → Notifications)
3. Check Do Not Disturb mode is off
4. Restart device
5. Reinstall app

Problem: Too many notifications

Solutions:

1. App Settings → Notifications → Customize
2. Disable non-essential alerts
3. Set quiet hours (iOS only)

Contribution Issues

Problem: "Contribution failed"

Solutions:

1. Verify contribution amount matches group requirement
2. Check XLM balance (including fees)
3. Ensure group is active (not paused or complete)
4. Check if you already contributed this cycle
5. Verify network connection
6. Try again in a few minutes

Problem: "Contribution not showing"

Solutions:

1. Pull down to refresh group screen
2. Check transaction history (Activity tab)
3. Verify transaction on Stellar Explorer (tap transaction → View on Explorer)
4. Wait for blockchain confirmation (usually <5 seconds)
5. Contact support if not resolved in 5 minutes

QR Code Issues

Problem: "Cannot scan QR code"

Solutions:

1. Grant camera permission (Settings → Stellar-Save → Camera)
2. Ensure good lighting
3. Hold device steady, 6-12 inches from code
4. Clean camera lens
5. Manually enter group ID instead (tap "Enter Manually")

Problem: "Invalid QR code"

Solutions:

1. Verify QR code is for Stellar-Save (not another app)
2. Ask sender to regenerate QR code
3. Try manual entry with group ID

Biometric Authentication Issues

Problem: Face ID/Touch ID not working

Solutions:

1. Verify biometrics work in other apps
2. Re-enroll biometrics in device settings
3. Use PIN as fallback (tap "Use PIN")
4. Disable and re-enable in app (Settings → Security → Biometric Authentication)

Problem: "Too many failed attempts"

Solutions:

1. Wait 30 seconds and try again
2. Use PIN instead
3. Restart app

Data Sync Issues

Problem: "Data out of sync"

Solutions:

1. Pull down to refresh
2. Check internet connection
3. Log out and log back in (Settings → Account → Sign Out)
4. Clear cache (Settings → Clear Cache)
5. Reinstall app (backup seed phrase first!)

Platform-Specific Issues

iOS Issues

Problem: App not updating in background

Solution: Settings → General → Background App Refresh → Enable for Stellar-Save

Problem: Widget not updating

Solution: Remove and re-add widget, or restart device

Android Issues

Problem: App killed by battery optimization

Solution: Settings → Apps → Stellar-Save → Battery → Unrestricted

Problem: Notifications delayed

Solution: Disable battery optimization for Stellar-Save

Offline Mode Details

What's Cached

The app stores recent data locally for offline access:

• Last 30 days of transaction history
• All group details and member lists
• Your wallet balance (last synced)
• App settings and preferences

Cache Size: ~10-50 MB depending on activity

Offline Limitations

Cannot Do Offline:

• Make contributions (requires blockchain transaction)
• Create or join groups
• Execute payouts
• Refresh real-time data
• Update group settings

Can Do Offline:

• View cached groups and history
• Read documentation and FAQ
• Check last known balance
• Plan future contributions
• Export transaction reports

Sync Behavior

Auto-Sync Triggers:

• App opens with internet connection
• Connection restored after offline period
• Manual pull-to-refresh
• Every 5 minutes when app is active

Sync Indicators:

• Green checkmark: Data is current
• Yellow clock: Syncing in progress
• Red warning: Sync failed, data may be stale

Conflict Resolution: Server data always takes precedence over cached data

Managing Offline Data

Clear Cache: Settings → Storage → Clear Cache (frees space, requires re-sync)

Download for Offline: Settings → Offline Mode → Download All Groups (pre-caches data)

Accessibility Features

Screen Reader Support

iOS VoiceOver

• All buttons and elements are labeled
• Swipe right/left to navigate
• Double-tap to activate
• Three-finger swipe to scroll

Android TalkBack

• Full screen reader support
• Swipe gestures for navigation
• Explore by touch enabled

Enable: Device Settings → Accessibility → VoiceOver/TalkBack

Visual Accessibility

Large Text: Supports Dynamic Type (iOS) and Font Size (Android)

• Device Settings → Display → Text Size

High Contrast: Automatically adapts to system high contrast mode

Color Blind Mode: Settings → Accessibility → Color Blind Friendly (uses patterns + colors)

Reduce Motion: Respects system reduce motion settings (disables animations)

Hearing Accessibility

Visual Alerts: All audio alerts have visual equivalents (flashes, banners)

Haptic Feedback: Vibration confirms actions for users who can't hear audio cues

Motor Accessibility

Large Touch Targets: All buttons meet minimum 44x44pt size

Simplified Gestures: All swipe actions have button alternatives

Voice Control: Compatible with iOS Voice Control and Android Voice Access

Tips & Best Practices

Battery Optimization

• Enable dark mode
• Reduce notification frequency
• Disable background refresh if not needed
• Close app when not actively using

Data Usage

• App uses ~1-5 MB per month for typical usage
• Downloading group data: ~100 KB per group
• Transactions: ~1 KB each
• Use WiFi for initial setup and large syncs

Security Best Practices

1. Enable Biometrics: Faster and more secure than PIN
2. Backup Seed Phrase: Write it down, store securely offline
3. Use Strong PIN: 6+ digits, not birthdate or simple patterns
4. Enable Auto-Lock: Settings → Security → Auto-Lock → 1 minute
5. Verify Addresses: Always double-check recipient addresses
6. Beware Phishing: Only download from official app stores

Performance Tips

• Keep app updated to latest version
• Restart app weekly to clear memory
• Clear cache monthly (Settings → Clear Cache)
• Maintain 100+ MB free storage on device
• Close other apps if experiencing lag

Group Management on Mobile

• Use widgets for quick status checks
• Enable contribution reminders
• Favorite important groups (swipe right)
• Use QR codes to invite members in person
• Check notifications daily

Getting Help

In-App Support

• Help Center: Settings → Help & FAQ
• Contact Support: Settings → Contact Support (includes device info automatically)
• Report Bug: Settings → Report a Problem

Community Support

• Telegram: @StellarSave
• Discord: discord.gg/stellarsave
• GitHub: github.com/Xoulomon/Stellar-Save/issues

Emergency Support

Lost Access: If you lose your device but have your seed phrase, install the app on a new device and restore your wallet.

Compromised Wallet: If you suspect your wallet is compromised:

1. Immediately transfer funds to a new wallet
2. Create new wallet with new seed phrase
3. Leave all groups (if possible)
4. Contact support

App Critical Bug: If the app is unusable:

1. Check for updates in app store
2. Visit status.stellar.org for network issues
3. Use web version at app.stellarsave.io as backup
4. Contact support with device details

Screenshots Guide

Note: Screenshots will be added when the mobile app is released. This section describes what will be shown.

iOS Screenshots

1. Home Dashboard - Overview of active groups and balance
2. Group Details - Detailed view of a savings group
3. Contribution Flow - Step-by-step contribution process
4. Wallet Screen - Balance and transaction history
5. QR Code Scanner - Joining a group via QR code
6. Notifications - Push notification examples
7. Widgets - Home screen widget variations
8. Dark Mode - App appearance in dark mode

Android Screenshots

1. Home Dashboard - Material Design interface
2. Group List - Swipe actions demonstration
3. Contribution Screen - Making a contribution
4. Navigation Drawer - Side menu navigation
5. Widgets - Android widget examples
6. Biometric Auth - Fingerprint authentication
7. Offline Mode - Offline indicator and cached data
8. Settings - App configuration options

Frequently Asked Questions

General Mobile Questions

Q: Is the mobile app free? A: Yes, the app is completely free. You only pay Stellar network fees (~0.00001 XLM per transaction).

Q: Which is better, iOS or Android version? A: Both versions have feature parity. Choose based on your device.

Q: Can I use the same wallet on mobile and web? A: Yes, import your seed phrase to access the same wallet on any platform.

Q: Does the app work on tablets? A: Yes, optimized for both phones and tablets (iPad and Android tablets).

Q: Is my data private? A: Yes, all data is stored locally or on the blockchain. We don't collect personal information.

Technical Questions

Q: Why does the app need camera permission? A: Only for scanning QR codes to join groups or send XLM. You can deny and enter IDs manually.

Q: Why does the app need notification permission? A: To alert you about contributions, payouts, and group updates. Optional but recommended.

Q: Can I use the app without biometrics? A: Yes, you can use a PIN instead. Biometrics are optional but recommended.

Q: How much storage does the app use? A: 50-100 MB for the app, plus 10-50 MB for cached data.

Q: Does the app work on older devices? A: Requires iOS 14+ or Android 8+. Older devices are not supported.

Troubleshooting Questions

Q: Why is my contribution not showing? A: Blockchain confirmations take 3-5 seconds. Pull down to refresh. If still missing after 5 minutes, check transaction history.

Q: The app keeps crashing, what do I do? A: Update to latest version, restart device, or reinstall (backup seed phrase first!).

Q: I forgot my PIN, how do I reset it? A: You cannot reset your PIN. You must reinstall and restore with your seed phrase.

Q: Can I recover my wallet without the seed phrase? A: No. The seed phrase is the only way to recover your wallet. Always keep it backed up securely.

Version History

v1.0.0 (Upcoming)

• Initial mobile app release
• iOS and Android support
• Core ROSCA functionality
• Biometric authentication
• Push notifications
• QR code scanning
• Offline mode
• Home screen widgets

Future Updates

• Multi-language support
• In-app XLM purchases
• Advanced analytics
• Group chat
• Recurring contribution automation
• Apple Watch / Wear OS support

---

Need more help? Visit our main user guide or contact support through the app.

Ready to get started? Download Stellar-Save from the App Store or Google Play.