sure/docs/hosting/native.md

# Turbo Native Hosting Guide

This guide explains how to build and ship the iOS and Android shells that host the Sure web experience via Hotwire Native. It assumes you have already cut the `feature/hotwire-native-prototype` branch and merged the Rails changes documented in `docs/hotwire_native_prototype_plan.md`.

## 1. Account & Access Checklist

| Platform | Required Accounts | Notes |
| --- | --- | --- |
| Apple iOS | Apple Developer Program (Individual or Company) | One team owner must invite the rest of the mobile crew via App Store Connect. Enable access to Certificates, Identifiers & Profiles. |
| Google Android | Google Play Console & Google Cloud project | Grant release managers the "Release manager" role and ensure a linked Firebase project for crash reporting (optional but recommended). |
| Source Control | GitHub (or host of record) access to the `feature/hotwire-native-prototype` branch | Keep Rails and native wrappers in sync by rebasing on `main` before every release build. |
| Distribution | TestFlight and Google Play Internal testing tracks | Set up at least one internal track per platform for QA builds. |

## 2. Local Development Environment

### Shared prerequisites

1. **Ruby & Node** – Match the versions declared in `.ruby-version` and `.node-version`. Run `bin/setup` once to install gems, npm packages, and prepare the Rails application.
2. **Hotwire Native CLI** – Install via `gem install hotwire-native` (requires Ruby 3.1+). This provides the `hotwire-native ios` and `hotwire-native android` commands used below.
3. **Environment files** – Copy `.env.local.example` to `.env.native`. Populate API hosts, feature flags, and any third-party keys required by the mobile shell. Do **not** commit secrets; use 1Password or the shared vault to distribute them.
4. **HTTPS tunnel** – For simulator work, expose your Rails dev server over HTTPS (e.g., `cloudflared tunnel` or `ngrok http https://localhost:3000`). The native apps refuse clear-text HTTP when ATS/Network Security Config is enabled.

### macOS requirements (iOS builds)

- macOS 13 Ventura or newer.
- Xcode 15.x with the Command Line Tools installed (`xcode-select --install`).
- CocoaPods (`sudo gem install cocoapods`) for dependency syncing.
- Homebrew (optional) for installing simulators and utilities.

### Windows/Linux requirements (Android builds)

- Android Studio Giraffe+ with Android SDK Platform 34.
- Java 17 (Android Gradle Plugin 8 requires it).
- `adb` available in your `$PATH`.
- Gradle managed through Android Studio (wrapper checked into the native repo).

## 3. Repository Layout

The prototype keeps the native wrappers under `native/` alongside the Rails app:

```
native/
├── ios/           # Xcode workspace generated by hotwire-native
├── android/       # Gradle project for the Android shell
└── README.md      # Shared notes specific to the wrappers
```

If `native/` does not exist yet, initialize it with:

```sh
hotwire-native init --platforms=ios,android --path=native \
  --app-name "Sure" \
  --server-url "https://dev.sure.example" # replace with your tunnel URL
```

Commit the scaffolding to the prototype branch so others can collaborate.

## 4. Configuring the WebView bridge

1. Update `native/ios/Sure/Info.plist` and `native/android/app/src/main/AndroidManifest.xml` with the production domain (`https://app.sure.com`).
2. Ensure the Rails layout `app/views/layouts/application.html+turbo_native.erb` serves navigation payloads. No code change is required, but verify the JSON includes the tabs expected by the native shell.
3. Add your HTTPS tunnel domain to the allow-list during development:
   - **iOS**: `NSAppTransportSecurity -> NSAllowsArbitraryLoadsInWebContent = YES` for the tunnel hostname only.
   - **Android**: Update `res/xml/network_security_config.xml` to allow the dev hostname over HTTPS.

## 5. Building the iOS app

```sh
cd native/ios
pod install
xed . # or open Sure.xcworkspace manually
```

1. Select the `Sure` scheme.
2. Choose a signing team that matches your Apple Developer account.
3. Configure the bundle identifier under *Signing & Capabilities* (e.g., `com.sure.app` for production, `com.sure.dev` for staging).
4. Update the build settings:
   - **Server URL**: Edit `Config.xcconfig` to point to your desired environment (`https://staging.sure.com`).
   - **App Icon & Assets**: Replace the placeholder images in `Assets.xcassets`.
5. To run in the simulator, press **⌘R**. For a physical device, ensure it is registered in the Developer portal and use **Product → Destination** to select it.
6. Create an archive (**Product → Archive**) and upload to TestFlight using the Organizer. Document the build number in the release notes.

## 6. Building the Android app

```sh
cd native/android
./gradlew wrapper
./gradlew assembleDevDebug # dev tunnel build
./gradlew assembleRelease  # production-ready build (requires keystore)
```

1. In Android Studio, open the `native/android` folder.
2. Set the application ID in `app/build.gradle` (`applicationId "com.sure.app"`). Use suffixes like `.dev` for QA channels.
3. Update `app/src/main/res/xml/remote_config_defaults.xml` or equivalent to point to the correct server URL.
4. Configure signing:
   - Place the keystore under `native/android/keystores/` (ignored by git).
   - Add a `keystore.properties` file (ignored) with `storeFile`, `storePassword`, `keyAlias`, `keyPassword`.
   - Reference the file in `build.gradle` to enable release signing.
5. Verify the WebView bridge loads the Turbo Native layout by launching `devDebug` on an emulator (`Run > Run 'app'`).
6. Use the Play Console Internal track for QA: upload the `app-release.aab` generated by `./gradlew bundleRelease`.

## 7. Continuous Integration (Optional)

For automated builds, configure CI jobs to:

- Check out the Rails repo and run `bin/rails test` to ensure the web bundle is healthy.
- Cache `native/ios/Pods` and Android Gradle caches between runs.
- Use `xcodebuild -workspace Sure.xcworkspace -scheme Sure -archivePath ... archive` for iOS.
- Use `./gradlew bundleRelease` for Android.
- Store signed artifacts in the build pipeline or upload to App Store Connect / Play Console via API keys.

## 8. Release Checklist

1. Verify the Rails backend has been deployed with the matching commit hash.
2. Smoke-test the PWA to ensure parity with the native wrappers.
3. Update the in-app version string (Settings → About screen) to reflect the build.
4. Publish release notes describing the Turbo Native changes.
5. Coordinate rollout percentages (start with 5%, monitor, then ramp).

## 9. Support & Troubleshooting

- **Authentication loops**: Confirm `Turbo-Visit-Control` headers are present on sign-out routes and that cookies share the same domain between web and native shells.
- **Push notifications**: The prototype does not ship push support; add Firebase Cloud Messaging / APNs later.
- **Performance**: Use `WKWebView` and `androidx.webkit.WebViewCompat` debugging tools to profile slow pages. Enable remote debugging via Safari DevTools or `chrome://inspect`.

Keep this document updated as the prototype graduates from experimentation to production. Contributions should include simulator screenshots and updated instructions when the workflow changes.