Documentation

Product Overview

OviFlo is a Laravel + Flutter period tracking, fertility, mood, symptom, and wellness product. Everything you need to run a branded cycle-tracking app is included.

What's Included

• Laravel API backend with Sanctum authentication
• Tailwind-based admin dashboard
• Public landing page with admin-editable content
• Web installer (no SSH or command line required)
• Flutter mobile app (Android + iOS-ready source)
• App configuration API for ads, site content, and managed pages
• Google Play and Apple App Store billing verification endpoints
• English and Spanish localisation

Server Requirements

OviFlo requires a standard PHP hosting environment. Most cPanel/Plesk shared hosts meet these requirements.

Required PHP Extensions

Laravel Installation

OviFlo ships with a browser-based installer. No SSH or command line access is required for the initial setup.

What the Installer Does

• Writes .env with your database and app settings
• Generates APP_KEY
• Runs all database migrations
• Creates the first admin account
• Seeds default site settings
• Creates required upload and storage folders
• Creates .installed to lock the installer

Demo Credentials

After running the demo seeder, these accounts are available for review:

Admin Dashboard

After installation, log in to the admin panel at:

https://yourdomain.com/admin/login

Use the email and password you chose during the installer's admin setup step.

Available Sections

GET /api/app-config

Connect Flutter App to Backend

Before building the app, verify the backend is reachable by visiting these two URLs in a browser:

https://yourdomain.com/
https://yourdomain.com/api/app-config

/api/app-config must return JSON. A valid response confirms the API is live and accessible.

Build With Your Backend URL

APK (for direct install / testing):

cd oviflo_app

flutter build apk --release \
  --dart-define=API_BASE_URL="https://yourdomain.com"

App Bundle (for Play Store upload):

cd oviflo_app

flutter build appbundle --release \
  --dart-define=API_BASE_URL="https://yourdomain.com"

The app automatically derives all sub-paths:

Permanent Source Default

If you prefer not to pass --dart-define every time, edit the default directly in source:

oviflo_app/lib/core/constants/app_constants.dart

Change the defaultValue:

static const String baseUrl = String.fromEnvironment(
  'API_BASE_URL',
  defaultValue: 'https://yourdomain.com', // ← set your domain here
);

Then build normally without --dart-define.

App Setup

The Flutter project is in the oviflo_app/ folder. Each buyer should customise the app identity before building release apps.

Change App Name

OviFlo includes rename_app for changing the visible app name across all platforms:

cd oviflo_app
flutter pub get
dart run rename_app:main all="My Cycle App"

Platform-specific rename:

dart run rename_app:main android="My Cycle App" ios="My Cycle App"

Change Android Package Name

cd oviflo_app
flutter pub get
dart run change_app_package_name:main com.company.mycycle

After changing the package name:

• Replace android/app/google-services.json with one generated for the new package in Firebase Console.
• Update any Play Console package references.
• Update lib/core/constants/app_constants.dart default googlePlayPackage if needed.

Change iOS Bundle Identifier

1. Open oviflo_app/ios/Runner.xcworkspace in Xcode.
2. Select Runner in the project navigator.
3. Open Signing & Capabilities.
4. Change Bundle Identifier to e.g. com.company.mycycle.
5. Replace ios/Runner/GoogleService-Info.plist with the Firebase iOS file for the new identifier.

Change App Icon

1. Replace oviflo_app/assets/images/app_icon.png with your icon (1024×1024 PNG, no transparent background for iOS, centred mark with padding).
2. Run the icon generator:

cd oviflo_app
dart run flutter_launcher_icons

Runtime Build Overrides

The app supports --dart-define for multi-customer builds. All common identifiers can be overridden without editing source:

flutter build appbundle --release \
  --dart-define=APP_NAME="My Cycle App" \
  --dart-define=API_BASE_URL="https://yourdomain.com" \
  --dart-define=ANDROID_PACKAGE="com.company.mycycle" \
  --dart-define=GOOGLE_SERVER_CLIENT_ID="your-web-client-id.apps.googleusercontent.com" \
  --dart-define=PREMIUM_MONTHLY_ID="mycycle_premium_monthly" \
  --dart-define=PREMIUM_ANNUAL_ID="mycycle_premium_annual" \
  --dart-define=ADMOB_APP_ID="ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX" \
  --dart-define=PLAY_INTEGRITY_PROJECT_NUMBER="123456789012"

App Name vs Admin Site Name

There are two separate concepts buyers often confuse:

Flutter Requirements

Minimum environment for building OviFlo:

flutter --version

Local Development

To run the Flutter app against a local Laravel backend during development:

1. Start the Laravel Dev Server

php artisan serve

This listens on http://127.0.0.1:8000 by default.

2. Run Flutter Against the Local Server

On Android Emulator (uses 10.0.2.2 as alias for the host machine's 127.0.0.1):

cd oviflo_app
flutter run --dart-define=API_BASE_URL="http://10.0.2.2:8000"

On a physical device connected to the same network (replace with your machine's local IP):

flutter run --dart-define=API_BASE_URL="http://192.168.1.10:8000"

Authentication

OviFlo supports two independent sign-in methods. Either works without the other.

Email and Password

Email/password uses the Laravel API directly with no Firebase dependency. This works in any market, including regions without Google Play:

Google Sign-In

Google Sign-In requires Firebase Authentication. The full flow:

Google Sign-In will fail if:

• google-services.json has not been replaced with the buyer's own Firebase project file
• The app's SHA-1 fingerprint has not been added to Firebase Console
• FIREBASE_PROJECT_ID has not been set in the Laravel .env

Firebase Setup

Firebase is required only for Google Sign-In. Email/password login works without it. You must create your own Firebase project before publishing. Do not ship production apps using the placeholder Firebase config included in the package.

1. Create a Firebase Project

1. Open console.firebase.google.com
2. Click Add project and enter the app name
3. Analytics is optional. Enable only if you plan to use Firebase/Google Analytics.
4. Finish project creation

2. Enable Google Authentication

1. Open the Firebase project
2. Go to Build → Authentication → Get started
3. Open Sign-in method
4. Enable Google, set a public support email, and save

3. Register the Android App

Change the Flutter package name first, then in Firebase:

cd oviflo_app
dart run change_app_package_name:main com.company.mycycle

1. Go to Project settings → Your apps → Android icon
2. Enter the Android package name (must match applicationId in build.gradle.kts exactly)
3. Add SHA fingerprints (see step 4 below)
4. Register the app

4. Add SHA Fingerprints

Firebase needs Android signing certificate fingerprints so Google Sign-In trusts requests from the installed app. Add both SHA-1 and SHA-256.

For debug builds:

cd oviflo_app/android
./gradlew signingReport

Copy SHA-1 and SHA-256 for the debug variant into Firebase Console.

For release builds, use the release keystore:

keytool -list -v \
  -keystore /path/to/release-key.jks \
  -alias your_key_alias

5. Download Firebase Config Files

Download from Firebase and replace the placeholder files:

After changing fingerprints, always download a fresh google-services.json.

6. Regenerate Flutter Firebase Options

npm install -g firebase-tools
dart pub global activate flutterfire_cli
firebase login

cd oviflo_app
flutterfire configure

This regenerates oviflo_app/lib/firebase_options.dart.

7. Set the Google Server Client ID

Find the Web OAuth client ID in:

• Firebase Console → Project settings → General → Your apps → Web client ID
• Or Google Cloud Console → APIs & Services → Credentials → OAuth 2.0 Client IDs → Web client

flutter build appbundle --release \
  --dart-define=API_BASE_URL="https://yourdomain.com" \
  --dart-define=GOOGLE_SERVER_CLIENT_ID="your-web-client-id.apps.googleusercontent.com"

8. Backend Config

Set FIREBASE_PROJECT_ID in the Laravel .env to your Firebase project ID (found in Firebase Console → Project settings → General):

FIREBASE_PROJECT_ID=your-firebase-project-id

The Laravel API endpoint that handles the Firebase token is already included:

POST /api/v1/auth/firebase

Google Play Billing

OviFlo uses Flutter's in_app_purchase package to query Play products, open the purchase sheet, listen for updates, and restore purchases. Server-side verification prevents fraud.

Default Product IDs

These must match Play Console exactly (case-sensitive). Override at build time:

flutter build appbundle --release \
  --dart-define=API_BASE_URL="https://yourdomain.com" \
  --dart-define=PREMIUM_MONTHLY_ID="buyer_premium_monthly" \
  --dart-define=PREMIUM_ANNUAL_ID="buyer_premium_annual"

1. Create Subscription Products in Play Console

Go to Monetize with Play → Products → Subscriptions and create both products. Each subscription needs an active base plan. If you want the app's "14-day free trial" text to be accurate, configure a trial offer on the annual subscription.

2. Google Play Developer API Credentials

Laravel needs a service account to verify purchases server-side:

1. Open Google Cloud Console and create a service account
2. Download a JSON key for that service account
3. Go to Play Console → Setup → API access
4. Link the Google Cloud project
5. Grant the service account access with minimum financial/subscription permissions
6. Store the JSON file outside the public web root (e.g. /home/user/secure/)
7. Add to Laravel .env:

GOOGLE_PLAY_PACKAGE_NAME=com.company.mycycle
GOOGLE_PLAY_SERVICE_ACCOUNT_JSON=/home/user/secure/google-play-service-account.json
GOOGLE_PLAY_PREMIUM_PRODUCT_IDS=buyer_premium_monthly,buyer_premium_annual

3. Play Integrity Setup

OviFlo sends a Play Integrity token with purchase verification requests to reduce fraud.

1. Enable the Play Integrity API in Google Cloud Console
2. Go to Play Console → Setup → App integrity → Play Integrity API
3. Link the Google Cloud project and copy the project number

flutter build appbundle --release \
  --dart-define=API_BASE_URL="https://yourdomain.com" \
  --dart-define=ANDROID_PACKAGE="com.company.mycycle" \
  --dart-define=PLAY_INTEGRITY_PROJECT_NUMBER="123456789012"

4. Add License Testers

To test paid subscriptions without real charges:

• Add tester Gmail accounts in Play Console → Settings → License testing
• Also add those emails to Testing → Internal testing → Testers
• The tester must install the app from the Play Store testing link (not sideloaded)

Verification Request

The Flutter app posts completed purchases to:

POST /api/v1/billing/google/verify

{
  "product_id": "oviflo_premium_monthly",
  "purchase_token": "google-play-purchase-token",
  "package_name": "com.company.mycycle"
}

On success, the response includes premium_until and an updated user object.

Common Failure Causes

AdMob Ads Setup

Ad settings are managed entirely from the admin panel. No code changes are needed to switch between test and live mode.

How Ad Configuration Works

On startup, the Flutter app fetches ad configuration from /api/app-config. This returns the current ad settings including test_mode, enabled placements, and ad unit IDs. The app caches this response locally so it works offline after the first load.

1. Create an AdMob Account

1. Go to admob.google.com
2. Create an Android app in AdMob
3. Copy the AdMob App ID (format: ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX)
4. Create 4 ad units: Banner, Interstitial, Rewarded, Native

2. Replace the AdMob App ID

The AdMob App ID must be set in two places:

Flutter source: Edit lib/core/constants/app_constants.dart and replace the default value:

static const String admobAppId = String.fromEnvironment(
  'ADMOB_APP_ID',
  defaultValue: 'ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX', // ← replace
);

Or pass at build time (no source edit needed):

flutter build apk --release \
  --dart-define=API_BASE_URL="https://yourdomain.com" \
  --dart-define=ADMOB_APP_ID="ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX"

Android manifest: In android/app/build.gradle.kts, update the fallback value:

val admobId = System.getProperty("ADMOB_APP_ID")
    ?: project.findProperty("ADMOB_APP_ID") as String?
    ?: "ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX" // ← replace this fallback

3. Replace Ad Unit IDs

Pass all ad unit IDs at build time:

flutter build apk --release \
  --dart-define=API_BASE_URL="https://yourdomain.com" \
  --dart-define=ADMOB_APP_ID="ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX" \
  --dart-define=ADMOB_BANNER_ID="ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX" \
  --dart-define=ADMOB_INTERSTITIAL_ID="ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX" \
  --dart-define=ADMOB_REWARDED_ID="ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX" \
  --dart-define=ADMOB_NATIVE_ID="ca-app-pub-XXXXXXXXXXXXXXXX/XXXXXXXXXX"

4. Enable Live Ads

1. Log in to the admin panel at /admin/login
2. Go to Ad Settings
3. Enter your live ad unit IDs
4. Turn off Test Mode
5. Save. The Flutter app picks up the change on next launch.

Health Connect Setup

OviFlo reads sleep, steps, heart rate, and activity data from Android Health Connect.

Requirements

• Android 9.0 (API 28) or higher
• Health Connect app installed (pre-installed on Android 14+; available on the Play Store for older versions)
• User must grant permissions inside the Health Connect app

Permissions Requested

Health data is read-only, stored locally on the device, and never sent to the backend or third parties.

How It Works

The first time a user taps a Health Connect feature, the app checks if Health Connect is installed. If not, it shows a prompt to install from the Play Store. Once installed, the user is taken to the Health Connect permission screen for the specific permissions OviFlo requests.

Testing

On Android Emulator (API 34+), Health Connect is pre-installed. On older emulators, install the Health Connect APK from the Play Store. Use the Health Connect app to manually enter test data and it will appear in OviFlo within seconds.

Release Keystore

You must create your own Android release keystore before publishing. Do not publish apps signed with the placeholder key.properties included in the package.

1. Generate a Keystore

keytool -genkey -v \
  -keystore /path/to/your-release-key.jks \
  -alias your_key_alias \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

You will be prompted for a password, name, and organisation details. Store this file securely. If you lose it you cannot update the app on the Play Store.

2. Update key.properties

Edit oviflo_app/android/key.properties:

storePassword=your_keystore_password
keyPassword=your_key_password
keyAlias=your_key_alias
storeFile=/absolute/path/to/your-release-key.jks

3. Add SHA-1 to Firebase

Release builds require the release keystore SHA-1 in Firebase Console for Google Sign-In to work.

keytool -list -v \
  -keystore /path/to/your-release-key.jks \
  -alias your_key_alias

Copy the SHA1 value and add it in Firebase Console → Project settings → Your apps → Android app → SHA certificate fingerprints.

Download a fresh google-services.json after adding the fingerprint.

Splash Screen Customisation

OviFlo has two splash layers that together cover the app startup experience.

Layer 1: Native Android Frame

Shown immediately when the app launches, before Flutter loads.

File: oviflo_app/android/app/src/main/res/drawable/launch_background.xml

To change the background colour, edit:

oviflo_app/android/app/src/main/res/values/colors.xml

<color name="app_background">#EAE2FF</color>

To add a centred logo on the native frame, add a <bitmap> item inside launch_background.xml:

<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@color/app_background"/>
    <item>
        <bitmap
            android:gravity="center"
            android:src="@drawable/splash_logo"/>
    </item>
</layer-list>

Then place your splash_logo.png in res/drawable/. Repeat for drawable-v21/launch_background.xml.

Layer 2: Flutter Splash Screen

Shown after the Flutter engine loads. Contains the animated logo, app name, and tagline.

File: oviflo_app/lib/features/onboarding/screens/splash_screen.dart

Edit this file to change the logo widget, tagline, or colours shown during the Flutter initialisation phase.

Localisation

OviFlo ships with English and Spanish translations. The app automatically uses the device language if it matches a supported locale, falling back to English otherwise.

Translation Files

Adding a New Language

1. Copy app_en.arb to app_XX.arb (where XX is the BCP 47 language code, e.g. fr for French)
2. Translate the string values. Do not change the keys.
3. Add the new locale to supportedLocales in lib/main.dart:

supportedLocales: const [
  Locale('en'),
  Locale('es'),
  Locale('fr'), // ← add your language here
],

cd oviflo_app
flutter gen-l10n

Post-Install Notes

After the web installer completes, work through this checklist before going live:

• Log in to /admin/login with the credentials you set during installation
• Update Home Page content: hero text, features, CTA button, logo
• Update About, Privacy Policy, and Terms of Service pages
• Configure Ad Settings with your AdMob IDs (or leave test mode on)
• Set FIREBASE_PROJECT_ID in .env if using Google Sign-In
• Set Google Play billing credentials in .env if using Premium subscriptions
• Configure MAIL_* settings in .env for password reset emails
• Build the Flutter app with --dart-define=API_BASE_URL pointing to your domain
• Test the API connectivity: visit https://yourdomain.com/api/app-config and confirm JSON response
• Test sign in, sign up, and the main tracking features in the app

Troubleshooting

Support

What to Include in Your Request

• Your Envato purchase code
• A description of the issue and steps to reproduce it
• PHP version, Laravel version, and hosting environment
• Any relevant error messages from storage/logs/laravel.log
• Flutter and Dart versions (flutter --version)

Changelog