Employee App Setup

This guide covers setting up the Open Core Employee App for development and production deployment.

Requirements

Development Environment

Requirement	Version	Notes
Flutter SDK	3.9.2+	Required minimum
Android SDK	API 26+	Android 8.0 minimum
iOS SDK	Latest	For iOS builds (macOS only)
Java	17+	Required for Android builds
NDK	27.0.12077973	For native components

Backend Requirements

• Open Core Business Suite backend running and accessible
• API endpoint URL (e.g., https://your-domain.com/api/V1/)
• Firebase project configured for push notifications

Setup Steps

1. Clone Repository

git clone <repository-url>
cd apps/open_core_employee_app

2. Install Dependencies

flutter pub get

3. Configure Firebase

1. Create a Firebase project at Firebase Console
2. Add an Android app with your package name
3. Download google-services.json
4. Place it in android/app/google-services.json
5. For iOS, download GoogleService-Info.plist and add to ios/Runner/

The lib/firebase_options.dart file is auto-generated by the FlutterFire CLI. To regenerate it for your project:

dart pub global activate flutterfire_cli
flutterfire configure

This will automatically update lib/firebase_options.dart with your Firebase configuration.

4. Configure API Base URL

Update the API base URL in lib/api/api_routes.dart:

class APIRoutes {
  // For local development
  static const baseURL = "http://192.168.1.x:8000/api/V1/";

  // For production
  // static const baseURL = "https://your-domain.com/api/V1/";
}

5. Generate Code

The app uses MobX for state management and Hive for local storage. Generate required code:

dart run build_runner build --delete-conflicting-outputs

For continuous code generation during development:

dart run build_runner watch --delete-conflicting-outputs

6. Run the App

# Run in debug mode
flutter run

# Run on specific device
flutter run -d <device_id>

# List available devices
flutter devices

Production Build

Android APK

# Build release APK
flutter build apk --release

# Build split APKs by ABI (smaller file sizes)
flutter build apk --release --split-per-abi

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

Android App Bundle (for Play Store)

flutter build appbundle --release

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

iOS Build

# Build iOS release
flutter build ios --release

# Open in Xcode for archive and distribution
open ios/Runner.xcworkspace

Customization

App Branding

1. App Name: Update in android/app/src/main/AndroidManifest.xml and ios/Runner/Info.plist
2. Package Name: Update applicationId in android/app/build.gradle
3. App Icons: Replace icons in android/app/src/main/res/ and use flutter_launcher_icons

Theme Colors

Update colors in lib/utils/app_colors.dart:

const opPrimaryColor = Color(0xFF696cff);
const opSecondaryColor = Color(0xFF673AB7);
// Add your brand colors

Troubleshooting

Common Issues

Build fails with code generation errors

flutter clean
flutter pub get
dart run build_runner build --delete-conflicting-outputs

Firebase not initialized

Ensure google-services.json is in the correct location and Firebase is initialized in main.dart.

API connection issues

1. Verify backend is running and accessible
2. Check API base URL configuration
3. Ensure device/emulator can reach the backend network

Permission issues on Android

The app requires location permissions for attendance. Ensure these are declared in AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Next Steps

• Explore Features - Learn about app capabilities