# Datafy Ai

A new Flutter project.

## Repository

- **Remote:** `https://tanya39@bitbucket.org/overdrive/flutter_app.git`
- **CI/CD branch:** Pushing to the `develop` branch triggers build and deploy to Play Store internal testing.

```bash
# Clone
git clone https://tanya39@bitbucket.org/overdrive/flutter_app.git
cd flutter_app

# Push to develop to trigger internal deploy
git checkout develop
git push origin develop
```

## Documentation

- System scope: `../COMPREHENSIVE_SCOPE.md`
- Project documentation (guides, changelog, knowledge base): `../documentation/`

## App icons and assets

- **Source of truth:** `appicons/AppIcons/` — use the PNGs here for store listings and icon updates.
  - `Assets.xcassets/AppIcon.appiconset/` — iOS app icon set (1024, 180, 120, 87, 80, 60, 58, 57, 40, 29, etc.).
  - `appstore.png` / `playstore.png` — store listing assets.
- **Regeneration:** Android mipmaps and web icons are generated from `appicons/AppIcons/Assets.xcassets/AppIcon.appiconset/1024.png`. After changing that 1024 image, run: `dart run flutter_launcher_icons`.
- **iOS:** `ios/Runner/Assets.xcassets/AppIcon.appiconset/` is synced from `appicons/AppIcons/Assets.xcassets/AppIcon.appiconset/` (numeric filenames + `Contents.json`). Do not regenerate iOS from flutter_launcher_icons; keep using the appicons set.

## Getting Started

FlutterFlow projects are built to run on the Flutter _stable_ release.

## Test pipeline before push

From repo root (PowerShell):

```powershell
.\scripts\test-pipeline-local.ps1
```

- Runs `flutter pub get` and `flutter build appbundle --release` (same as CI).
- For local release signing: copy `android/key.properties.example` to `android/key.properties`, fill in passwords and place your keystore (e.g. `datafy-app-h1tv3h-keystore.jks`) in `android/app/`. If missing, the script warns and the build will fail at signing (CI will still work with Bitbucket variables).
- Validate `bitbucket-pipelines.yml` syntax: [Bitbucket Pipelines Validator](https://bitbucket.org/product/pipelines/validator).

## CI/CD (Bitbucket Pipelines)

- Repo: `overdrive/flutter_app` on Bitbucket. The **develop** branch builds and deploys the Android AAB to the Play Store internal track.
- Configure Bitbucket Repository Variables before the first run. **Mark as Secured** where indicated:
  - `SUPABASE_URL` (e.g. `https://datafy.appmonitor.co.za` — can be unsecured)
  - `SUPABASE_ANON_KEY` (Supabase anon key — **Secured**)
  - `ANDROID_KEYSTORE_BASE64` (base64 of your keystore, e.g. `datafy-app-h1tv3h-keystore.jks`; one line, no newlines)
  - `ANDROID_STORE_PASSWORD`
  - `ANDROID_KEY_PASSWORD`
  - `ANDROID_KEY_ALIAS` (your key alias, e.g. `datafy-app-h1tv3h` — can be unsecured)
  - `ANDROID_PLAYSTORE_JSON_BASE64` (base64 of your **Google Play service account JSON** file only — not the keystore; one line, no newlines)
- First Play Console release must be created manually before API uploads.
- **Do not commit** `AuthKey_*.p8` (Apple), `credentials.txt`, or any `.jks` / `key.properties` / `playstore-credentials.json`; they are in `.gitignore`. If `AuthKey_*.p8` is already tracked, run `git rm --cached AuthKey_*.p8`.
- **Try without converting first:** Use your keystore as-is: base64-encode `datafy-app-h1tv3h-keystore.jks`, set `ANDROID_KEYSTORE_BASE64` and `ANDROID_KEY_ALIAS=datafy-app-h1tv3h` in Bitbucket, then run the pipeline. Only if you see **"Tag number over 30"** run `.\scripts\convert-keystore-jdk17.ps1` and update `ANDROID_KEYSTORE_BASE64` with the new base64 (see **Convert keystore to JDK 17/21 compatible format** in `bitbucket_pipelines_flutter_cicd.md`).

- Deploy step uses `android/Gemfile` and Ruby 3.2; run `bundle install` and `bundle exec fastlane internal` from `android/` in CI. If the pipeline fails with "doesn't seem to be a JSON file", ensure `ANDROID_PLAYSTORE_JSON_BASE64` is set to the base64-encoded **service account JSON** (from Google Cloud Console), not the keystore.

### iOS (TestFlight)

- The **develop** branch runs Android **and** iOS (build + deploy). iOS steps require a **self-hosted macOS runner** with labels `self.hosted` and `macos`. Bitbucket does not provide hosted macOS.
- **Runner setup and troubleshooting:** See **`BITBUCKET_MACOS_RUNNER_SETUP.md`** for step-by-step setup and fixing “Currently no online runner available that matches the required labels”.
- **Where to add a runner:** Repository **Settings** → **Pipelines** → **Runners** → **Add runner** → **MacOS (x86 / Apple Silicon)**. Or **Workspace settings** → **Pipelines** → **Workspace runners** → **Add runner**. Keep the default labels **self.hosted** and **macos**.
- Bitbucket variables for iOS (add alongside Android):
  - `IOS_APP_STORE_CONNECT_API_KEY_ID` (App Store Connect API Key ID)
  - `IOS_APP_STORE_CONNECT_ISSUER_ID` (Issuer ID)
  - `IOS_APP_STORE_CONNECT_API_KEY_BASE64` (base64 of your `.p8` key file; one line, **Secured**)
  - Optional for Match code signing: `MATCH_GIT_URL`, `MATCH_GIT_BASIC_AUTH` (base64 of `username:token`, **Secured**), `MATCH_PASSWORD` (**Secured**)
- Custom pipelines: **Run pipeline** → **Custom** → `build-ios` (build only) or `deploy-ios-testflight` (build + deploy to TestFlight).

See `BITBUCKET_MACOS_RUNNER_SETUP.md`, `bitbucket_pipelines_flutter_cicd.md`, `bitbucket_pipelines_flutter_cicd222.md` and `flutter_playstore_deployment_guide.md` for setup details.