Version 1.0.0Web + App

Mobile App (Flutter)

Configure, rebrand, build and publish the Android and iOS app.

Item: OmniGenix AI — web platform + Flutter app  ·  Stack: Flutter (Dart 3.12+) · GetX · Dio · Laravel 12 REST API v1

Before you start: Firebase and your own accounts. Push notifications use Firebase Cloud Messaging (FCM), a Google service. You create your own Firebase project, accept Google’s terms (Firebase / Google APIs Terms of Service) and are responsible for any Firebase charges and for the privacy disclosures in your store listings. No Firebase files ship with the item (no google-services.json, no GoogleService-Info.plist, no Firebase keys). Without them the app builds and runs normally; only push notifications are off (no device tokens are registered and no notification banners arrive; the in-app notification list still works through the API). Publishing also needs your own Apple Developer and Google Play Console accounts. The app has no Google Sign-In and no Sign in with Apple: users sign in with e-mail and password, so no OAuth clients are needed. Set-up: Firebase Push; costs: Accounts & Costs and Third-Party Services & Costs.

What the App Does

A native Flutter app for Android and iOS (no WebView wrapper) for the members of your customers’ companies. It talks only to your platform’s /api/v1 REST API with Sanctum bearer tokens; no AI provider keys or payment credentials are ever stored in the app. State management is GetX and the HTTP client is Dio. Version 1.0.0+1.

  • Account and workspace: login with the two-factor code step (authenticator or recovery code), registration (Terms acceptance required), e-mail-code verification, password reset, device sessions, workspace picker and switching, profile, biometric lock with PIN fallback.
  • Home: credit balance, plan and expiry, daily limit, usage this month and quick actions; low-credit, subscription and job alerts.
  • Studio: AI chat (streaming, history, attachments, prompt picker, voice input, read-aloud), Content, Image, Video, Voice (text-to-speech and speech-to-text), Document AI (with a document scanner), AI agents, Marketing tools, Content calendar, AI code, Avatar video, Projects, Files & assets and Brand Kit.
  • Library: generation history with filters and favourites; duplicate, remix and regenerate.
  • Settings: workspace, team and invitations, billing (wallet, plan, transactions, invoices; on Android top-ups open the web checkout in the external browser, on iOS there are no purchases in the app), projects, files, brand kit, theme light/dark/system, language English/Bangla/Arabic (RTL).
  • Mobile-native: FCM push with notification actions, deep links (omnigenix:// and app links), Android share intents, draft autosave, offline outbox that syncs when the connection returns, universal search, update-required gate, accessibility (dynamic text, screen-reader labels, contrast, reduced motion).

SaaS administration, provider credentials, payment-gateway configuration, CMS and system settings stay in the web admin.

Screens

Captured on an iPhone 16 Pro simulator against the seeded demo workspace.

Login
Login
Home
Home
Chats
Chats
Studio
Studio
Library
Library
Settings
Settings
Chat thread
Chat thread
Content studio
Content studio
Image studio
Image studio
Video studio
Video studio
Voice studio
Voice studio
AI code
AI code
AI agents
AI agents
Marketing tools
Marketing tools
Content calendar
Content calendar
Social publishing
Social publishing
Projects
Projects
Files & assets
Files & assets
Brand Kit
Brand Kit
Team
Team
Billing
Billing
Profile
Profile
Settings
Settings
Dark theme
Dark theme
Home, dark
Home, dark
Chat, dark
Chat, dark
Studio, dark
Studio, dark
Home, Arabic RTL
Home, Arabic RTL
Studio, Arabic RTL
Studio, Arabic RTL
Billing, Arabic RTL
Billing, Arabic RTL

Requirements

ItemNotes
Flutter SDKStable channel with Dart 3.12 or newer (pubspec.yaml: sdk: ^3.12.0)
AndroidAndroid Studio, JDK 17 and Android SDK Platform 37 (API level 37; Android Studio → SDK Manager → SDK Platforms). android/app/build.gradle.kts sets compileSdk = 37 (required by receive_sharing_intent), targetSdk = 36 and minSdk = 24 (Android 7.0), all explicit integers. Platform 37 is the only SDK platform you must install.
iOSA Mac with Xcode and CocoaPods; your own Apple Developer team. Deployment target iOS 15.0.
BackendA running OmniGenix AI web install reachable over HTTPS (release builds block plain HTTP)
Push (optional)Your own Firebase project (see Before You Start)
StoresGoogle Play Console and/or Apple Developer Program accounts

Setup & Run

cd AppSourceCode
flutter pub get
flutter gen-l10n
cp dart_defines.example.json dart_defines.json     # then edit API_BASE_URL (and FIREBASE_* for push)
flutter run --dart-define-from-file=dart_defines.json

API_BASE_URL is the root URL of your web install, e.g. https://app.example.com; a bare domain also works, and the app adds /api/v1 itself. If you pass nothing, the app uses the neutral placeholder https://omnigenix.example.com (AppConfig.placeholderBaseUrl in lib/core/config/app_config.dart), which does not exist: always set your own URL. In debug and profile builds testers can change the server at runtime by long-pressing the logo on the login screen; release builds always use the compiled URL.

Local development against php artisan serve: copy dart_defines.local.example.json instead (Android emulator reaches your computer at http://10.0.2.2:8000). Plain HTTP works only in debug builds.

flutter analyze
flutter test

dart_defines.json is gitignored; keep your real values out of version control.

--dart-define Keys

All configuration is passed at build time (--dart-define or --dart-define-from-file), so the repository holds no secrets (lib/core/config/app_config.dart, lib/core/services/push_service.dart).

DefineRequiredPurpose
API_BASE_URLyesYour platform URL, e.g. https://app.example.com. Must be HTTPS in release builds (cleartext is disabled). Default: placeholder https://omnigenix.example.com.
FIREBASE_API_KEY, FIREBASE_APP_ID, FIREBASE_SENDER_ID, FIREBASE_PROJECT_IDfor push, if you do not add the Firebase filesValues from Firebase console → Project settings → your app
FIREBASE_IOS_BUNDLE_IDfor iOS pushUsually the same as the bundle id
ANDROID_WEB_CHECKOUTnotrue (default): Android opens the web checkout for credit top-ups. false: no purchases in the Android app either (iOS never shows them).

Without the Firebase files or defines, Firebase initialisation is skipped silently and push notifications are disabled; everything else works.

Firebase Push

  1. Create your own Firebase project

    In the Firebase console, accept the terms, then add an Android app with your applicationId (default com.omnigenix.app) and an iOS app with your bundle id. Rebrand first (see Rebrand the App) so the ids match.

  2. Android

    Place google-services.json in android/app/. The Google Services Gradle plugin is applied only when that file exists. The file is gitignored.

  3. iOS

    Add GoogleService-Info.plist to ios/Runner/ in Xcode, keep the Push Notifications and Background Modes → Remote notifications capabilities, and upload your APNs authentication key (Apple Developer → Keys) in Firebase → Project settings → Cloud Messaging.

  4. Or use defines

    Instead of the two files you can pass the FIREBASE_* defines shown above.

  5. Server side

    In the web admin open Settings → Push Notifications, paste the service-account JSON of the same Firebase project (Project settings → Service accounts → Generate new private key) and save (see Web Platform → Push). Push is sent from the queue, so a queue worker or QUEUE_VIA_SCHEDULER=true must run.

FCM itself has no per-message fee; Firebase bills only for other products on the Blaze plan. Read the current Firebase pricing page for your project.

Sign-in Methods

The app signs users in with e-mail and password against /api/v1 (registration, e-mail-code verification and password reset included). It does not include Google Sign-In, Sign in with Apple or any other social login (pubspec.yaml has no google_sign_in or sign_in_with_apple package), so you do not need to create OAuth clients for the app. Because there is no third-party login, Apple’s rule that apps offering third-party sign-in must also offer Sign in with Apple does not apply.

The “social” OAuth apps configured in the web admin (Settings → Social publishing) are for publishing posts to companies’ social networks, not for signing in.

Share Extension

Android: intent filters let users share text, URLs, images and files from other apps into OmniGenix (via receive_sharing_intent). Nothing to configure.

iOS: the folder ios/ShareExtension contains the extension sources (ShareViewController.swift, Info.plist, and ShareExtension.entitlements with the App Group $(CUSTOM_GROUP_ID)). The Runner target already sets CUSTOM_GROUP_ID = group.com.omnigenix.app and uses the same group in Runner.entitlements and Info.plist (AppGroupId). The extension accepts text, URLs, up to 10 images and files.

In version 1.0.0 the ShareExtension target is not registered in ios/Runner.xcodeproj. To use the iOS share sheet, add a Share Extension target in Xcode that uses these files, give it a bundle id under your app id (e.g. com.yourcompany.yourapp.ShareExtension), set CUSTOM_GROUP_ID on it, and enable the same App Group on both the Runner and ShareExtension targets under Signing & Capabilities. The rest of the app builds and runs without it.

Rebrand the App

Do this before your first store upload: the package name / bundle id cannot be changed after publishing. Values below are the shipped defaults.

WhatDefaultWhere to change it
App name (home screen)OmniGenix AIandroid:label in android/app/src/main/AndroidManifest.xml; CFBundleDisplayName and CFBundleName in ios/Runner/Info.plist; AppConfig.appName in lib/core/config/app_config.dart. Also the app name inside the permission texts of Info.plist (NSFaceIDUsageDescription, camera, microphone, speech…) and the strings in lib/l10n/app_*.arb.
Android application id + namespacecom.omnigenix.appnamespace and applicationId in android/app/build.gradle.kts; move android/app/src/main/kotlin/com/omnigenix/app/MainActivity.kt to the matching folder and update its package line.
iOS bundle idcom.omnigenix.app (tests: com.omnigenix.app.RunnerTests)Xcode → Runner target → Signing & Capabilities (PRODUCT_BUNDLE_IDENTIFIER in ios/Runner.xcodeproj/project.pbxproj). Also set MOBILE_IOS_BUNDLE_ID and MOBILE_ANDROID_PACKAGE in the web .env.
Development teamnone (empty)Xcode → Runner target → Signing & Capabilities → Team: pick your team. The project ships without a team id.
App Group (share extension)group.com.omnigenix.appCUSTOM_GROUP_ID build setting of the Runner target (and of the ShareExtension target if you add it); register the group in your Apple Developer account.
Custom URL schemeomnigenixandroid:scheme="omnigenix" in AndroidManifest.xml, CFBundleURLSchemes (and CFBundleURLName com.omnigenix.app.deeplink) in Info.plist, and the scheme check in lib/core/services/deep_link_service.dart.
App-link / Universal-link hostomnigenix.example.comGradle property appLinkHost (Android) and APP_LINK_HOST build setting (iOS); see Deep Links.
Coloursseed #6D4AFF, primary #5B4FE9, secondary #0EA5E9lib/app/theme/app_theme.dart (light and dark schemes, surfaces, cards).
Logo inside the appassets/brand/omnigenix-mark.pngReplace the PNG (keep the file name, or change the path in pubspec.yaml → flutter: assets: and in the code that loads it).
Launcher iconOmniGenix iconflutter_launcher_icons is already configured in pubspec.yaml (dev dependency plus a flutter_launcher_icons: block for Android and iOS). Replace the 1024×1024 PNGs it points to with your own: assets/brand/launcher-foreground.png and launcher-background.png (Android adaptive icon), assets/brand/omnigenix-mark.png (older Android) and assets/brand/launcher-ios.png (iOS, full square, no transparency). Then run dart run flutter_launcher_icons; it rewrites android/app/src/main/res/mipmap-* and ios/Runner/Assets.xcassets/AppIcon.appiconset.
Splash / launch screenwhite backgroundAndroid: android/app/src/main/res/drawable*/launch_background.xml and values*/styles.xml; iOS: ios/Runner/Base.lproj/LaunchScreen.storyboard and Assets.xcassets/LaunchImage.imageset. No flutter_native_splash config ships; add it if you prefer generating the splash.
Version1.0.0+1version: in pubspec.yaml (version name + build number); raise the build number for every store upload.
Strings / languagesen, bn, ar (660 keys each)lib/l10n/app_en.arb, app_bn.arb, app_ar.arb, then flutter gen-l10n; CFBundleLocalizations in Info.plist.
Server URLplaceholder https://omnigenix.example.comAPI_BASE_URL define (see --dart-define Keys) or placeholderBaseUrl in app_config.dart.
Server switchdebug builds onlyLong-pressing the logo on the login screen opens a server field in debug and profile builds (AppConfig.serverOverrideEnabled). Release builds have no server switch and no demo login; nothing to remove before you publish.

After renaming ids, run flutter clean && flutter pub get, then cd ios && pod install, and add the new ids in Firebase (new google-services.json / GoogleService-Info.plist).

Android Release

  1. Create an upload keystore once

    keytool -genkey -v -keystore ~/omnigenix-upload.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

  2. Add key.properties

    Copy android/key.properties.example to android/key.properties and fill in storeFile, storePassword, keyAlias, keyPassword. The file is gitignored: never commit it or the keystore, and back both up (a lost upload key needs a Play support reset).

  3. Build

    Use the command below. flutter build apk --release builds a sideloadable APK instead.

ORG_GRADLE_PROJECT_appLinkHost=app.example.com \
  flutter build appbundle --release \
  --obfuscate --split-debug-info=build/symbols \
  --dart-define-from-file=dart_defines.json
  • Signing is required. A release build (flutter build apk|appbundle, flutter run --release) stops before compiling with RELEASE SIGNING NOT CONFIGURED when android/key.properties is missing or incomplete. There is no debug-key fallback. Debug and profile builds need no keystore.
  • R8 is on for release builds (isMinifyEnabled = true, isShrinkResources = true, rules in android/app/proguard-rules.pro). Release builds also disable cleartext HTTP.
  • Dart obfuscation: --obfuscate --split-debug-info=build/symbols obfuscates Dart code and writes the symbol files to build/symbols. Keep that folder for every release; you need it to read crash stack traces (flutter symbolize -i <trace> -d build/symbols/app.android-arm64.symbols).

iOS Release

  1. Open the workspace

    ios/Runner.xcworkspace in Xcode (run pod install in ios/ first).

  2. Signing

    The project ships without a development team. Select your own Team and set your bundle id on the Runner target (and on the ShareExtension target if you add it). Register the App Group and the Associated Domains capability for your id, and set APP_LINK_HOST for Universal Links.

  3. Build

    flutter build ipa --release --obfuscate --split-debug-info=build/symbols --dart-define-from-file=dart_defines.json

  4. Upload

    Upload build/ios/ipa/*.ipa with Xcode Organizer or Transporter.

Runner.entitlements sets aps-environment to development; Xcode switches it to production for App Store / TestFlight builds.

Version Gate

The app calls GET /api/v1/app/version on start. Set these in the web .env after you publish: MOBILE_ANDROID_LATEST_VERSION, MOBILE_ANDROID_MIN_VERSION, MOBILE_ANDROID_STORE_URL and the MOBILE_IOS_* equivalents, plus MOBILE_RELEASE_NOTES. Below the latest version the app prompts to update; below the minimum it shows the update-required screen. MOBILE_MAINTENANCE=true with MOBILE_MAINTENANCE_MESSAGE shows a maintenance notice. Publish the new build first, then raise the versions, then run php artisan config:clear.

Store Submission

  • Own package/bundle id, app name, icons, splash and signing (your upload keystore, your own Apple team).
  • API_BASE_URL points at your production HTTPS domain; https://YOUR-DOMAIN/api/v1/ping answers pong.
  • Build in release mode: release builds have no demo login and no runtime server switch.
  • Privacy policy URL: the platform serves CMS pages at /page/{slug} (seeded Privacy Policy and Terms & Conditions); edit them for your business.
  • Store listings, screenshots and data-safety / privacy-label answers (the app uses camera, photos, microphone, speech recognition, Face ID and push; check the usage descriptions in Info.plist). Mention Firebase if you enable push.
  • Reviewer test account on your server with sample content and credits.

Purchases (App Store 3.1.1): the app does not use in-app purchase. On iOS it shows the credit balance, plan, transactions and invoices but no top-up packages, checkout links or “top up” prompts (StorePolicy in lib/core/config/store_policy.dart); companies buy credits on the website. On Android top-ups open your web checkout in the external browser. Where Google Play requires Play Billing for your app, build with --dart-define=ANDROID_WEB_CHECKOUT=false to hide purchases on Android too.

Account deletion (Apple 5.1.1(v), Google Play): signed-in users can delete their account in the app under Settings → Profile → Delete account and Privacy & data → Delete account. The app asks for the password and calls DELETE /api/v1/account; the server refuses staff accounts and sole owners of workspaces that still have other members (the message is shown in the dialog). For Google Play’s data-deletion form, use your web workspace’s Privacy & data page as the deletion URL.

Accounts & Costs for the App

The item includes the app source code only. You open and pay for these accounts yourself; prices are set by the providers and change, so check their current pricing pages.

ServiceNeeded forTypical cost (check current pricing)
Google Play ConsolePublishing the Android appOne-time registration fee (USD 25 at the time of writing)
Apple Developer ProgramTestFlight and App Store, push certificates/keys, App Groups, Associated DomainsYearly membership (USD 99 per year at the time of writing)
Firebase (FCM)Push notifications (optional)FCM is free on the Spark (no-cost) plan; the pay-as-you-go Blaze plan bills only for other Firebase products you choose to use
Your OmniGenix AI serverEverything the app shows (it is a client of your web install)Hosting, domain and SSL; AI provider and payment costs are covered in Web Platform → Third-Party Services & Costs
A Mac with XcodeBuilding and signing the iOS appHardware you provide (or a cloud Mac / CI service)

Project Layout

lib/
  app/          routes, bindings, theme (app_theme.dart), root widget
  core/         config (app_config.dart), API client, storage, services (session, push,
                deep links, drafts, offline queue, transfers, app lock, status), shared widgets
  data/         models and repositories (one per API area)
  modules/      one folder per screen group (auth, home, chat, studio, image, video,
                voice, code, documents, projects, files, team, billing, ...)
  l10n/         app_en.arb, app_bn.arb, app_ar.arb
assets/brand/   in-app logo
android/        Gradle project (key.properties.example, proguard-rules.pro)
ios/            Xcode project (Runner, ShareExtension sources)
dart_defines.example.json, dart_defines.local.example.json

New screens are registered in lib/app/routes/app_pages.dart; new strings go in lib/l10n/app_en.arb and are translated in the other two ARB files.

Troubleshooting

Find the symptom, read the likely cause, apply the fix. Server-side problems are covered in Web Platform → Troubleshooting.

Connecting to the server
Login asks for a 6-digit code, or the code is refused

Cause: the account has two-factor authentication turned on (users switch it on in the web app: user menu → Change Password → Two-factor authentication; company workspace Settings → Password & security, SaaS Admin Profile → Update password). The API answers auth/login with two_factor_required: true and a challenge_token; the app then shows its two-factor step and posts the code to POST /api/v1/auth/two-factor.

Fix: enter the current code from the authenticator app (check that the phone’s clock is set automatically), or tap Use a recovery code. The challenge expires after 5 minutes or 5 wrong codes; then sign in again. 429 = too many attempts. Lost phone and no recovery codes left: the server administrator can clear 2FA for that one account by setting two_factor_secret, two_factor_recovery_codes and two_factor_confirmed_at of its users row to NULL.

App: 404 on every request, or “cannot reach server”

Cause: API_BASE_URL was not passed (the app then uses the placeholder https://omnigenix.example.com), points to the wrong host, or the web server does not route /api/v1 (document root not set to public/).

Fix: Build with --dart-define=API_BASE_URL=https://YOUR-DOMAIN (in a debug build you can also long-press the logo on the login screen to change the server). https://YOUR-DOMAIN/api/v1/ping must return pong in a browser.

App: 401 or “session expired” right after login

Cause: The web server or a proxy strips the Authorization header, or the token was revoked (signed out from Devices & sessions).

Fix: Keep the HTTP_AUTHORIZATION rewrite rule in public/.htaccess (Apache) or pass the header through in Nginx/CDN; test with curl -H "Authorization: Bearer TOKEN" -H "Accept: application/json" https://YOUR-DOMAIN/api/v1/me. Sign in again if the token was revoked.

Works in debug, fails in the release build

Cause: The URL is plain http://; release builds block cleartext traffic.

Fix: Serve the platform over HTTPS with a valid certificate and use the https:// URL.

Push & links
Push notifications do not arrive

Cause: No google-services.json / GoogleService-Info.plist (or FIREBASE_* defines) in the build; the server’s service-account JSON is from a different Firebase project; no APNs key in Firebase (iOS); testing on the iOS simulator; notifications denied on the device; or no queue worker on the server.

Fix: Use one Firebase project for app and server, paste its service-account JSON in Settings → Push Notifications, upload the APNs key, test on a real device with notifications allowed, and keep the queue worker running (Settings → System Status shows pending and failed jobs).

Invite / project links open the browser instead of the app

Cause: assetlinks.json or apple-app-site-association is not served over HTTPS with the right package, SHA-256 fingerprint, team id and bundle id, or the build used a different appLinkHost / APP_LINK_HOST.

Fix: Set MOBILE_ANDROID_PACKAGE, MOBILE_ANDROID_SHA256, MOBILE_IOS_TEAM_ID, MOBILE_IOS_BUNDLE_ID in the web .env, php artisan config:clear, open https://YOUR-DOMAIN/.well-known/assetlinks.json to check, rebuild with the same host, then reinstall the app (Android verifies links at install time).

omnigenix:// links do nothing

Cause: You changed the scheme in one place only.

Fix: Keep the scheme identical in AndroidManifest.xml, Info.plist and deep_link_service.dart.

Building & signing
Android release build fails: “RELEASE SIGNING NOT CONFIGURED”

Cause: android/key.properties is missing or one of storeFile, storePassword, keyAlias, keyPassword is empty. This is intentional: release builds are never signed with the debug key.

Fix: Create the keystore and key.properties as in Android Release. storeFile is an absolute path or relative to android/app/.

Android build fails on the SDK version

Cause: Android SDK Platform 37 (API level 37) or JDK 17 is not installed.

Fix: Install them in Android Studio → SDK Manager and run flutter doctor.

Release app crashes on start but debug works

Cause: R8 removed a class used by reflection in a plugin you added.

Fix: Add a -keep rule for that package to android/app/proguard-rules.pro and rebuild; read the de-obfuscated stack trace with the files in build/symbols.

iOS: “Signing for Runner requires a development team” or provisioning profile errors

Cause: The project ships without a team; or the App Group / Associated Domains / Push capability is not enabled for your bundle id.

Fix: In Xcode → Runner → Signing & Capabilities pick your team, set your bundle id, and let Xcode register the capabilities (or create the App Group group.your.bundle.id and set CUSTOM_GROUP_ID to it).

“Update required” screen

Cause: The installed version is below MOBILE_*_MIN_VERSION on the server.

Fix: Install the newer build, or lower the minimum version in the web .env and run php artisan config:clear.