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:

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

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

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.