Mobile Utility App Template - Chronological Implementation TODO Plan (Template repo: ai-eng-template-mobile-utility-app) ============================================================================== INTENT ============================================================================== A cross-platform (iOS + Android) mobile utility-app template suitable for small consumer or small-business apps: trackers, journals, checklists, companion apps, simple field-data-entry apps, and one-screen utilities. The template ships with Expo + React Native, Firebase Auth + Firestore + Cloud Functions + Storage, a tab-bar shell, an offline-first cache, push notifications, in-app updates, and signed builds for both stores. It is designed so a small team can ship to TestFlight and Internal Testing in two weeks and to public stores in four to eight. OUT OF SCOPE: large game engines, AR-heavy apps, apps that need native modules beyond the Expo SDK without a clear plan, multi-tenant B2B apps, regulated medical-device software. High-level summary - Goal: a forkable Expo + React Native + Firebase utility-app starter that can hit both stores in 4-8 weeks. - Platform target: Expo SDK (latest LTS), React Native, EAS Build, TypeScript, Firebase Auth + Firestore + Cloud Functions + Cloud Storage + FCM, Sentry or Crashlytics for crashes. - Performance/security target: cold-start < 2.5s on a mid-range device, battery-friendly background sync, App Check enforced on every callable. - Rough delivery estimate: 4-8 weeks per customer customization. Phase 0 - Scope freeze, product definitions, and delivery guardrails (Effort: Medium) Dependencies: customer discovery workshop output. [ ] Freeze template scope: - [ ] confirm the template ships with: sign-in (Google + Apple + email-link), a tab-bar shell (Home, Add, Library, Profile), a single example entity with offline-first CRUD, push notifications, in-app-update prompt, settings (theme, notifications, sign-out, data export, account delete), and a deep-link handler. - [ ] confirm explicit OUT-OF-SCOPE: AR, ARKit/ARCore-heavy modules, payments inside the app store walled garden beyond simple consumable IAP (which is a separate engagement), and complex offline conflict resolution beyond last-write-wins per record. Phase 1 - Repository skeleton, tooling, and CI (Effort: Medium) Dependencies: scope freeze. [ ] Repository: - [ ] create `ai-eng-template-mobile-utility-app` on GitHub. - [ ] root `README.md` with rebrand steps (app name, bundle ID, icons, splash, primary color). [ ] Tooling: - [ ] Node 20 LTS, pnpm 9, Expo SDK latest LTS, TypeScript, ESLint, Prettier, Vitest, Detox or Maestro for E2E. - [ ] EAS configured for build profiles `development`, `preview`, `production`. - [ ] Firebase CLI, emulators (Auth, Firestore, Functions, Storage). [ ] CI (GitHub Actions): - [ ] lint, typecheck, unit tests on every PR. - [ ] EAS Build on `main` for `preview` profile. - [ ] tagged releases trigger `production` builds for TestFlight and Internal Testing. Potential gotchas: - [ ] bundle IDs cannot change after a store submission; lock them in the rebrand checklist before the first build. Phase 2 - Design system and token foundation (Effort: Small) Dependencies: Phase 1. [ ] Tokens and primitives via `react-native-unistyles` or a tokens-driven Tamagui setup: - [ ] color, type scale, spacing, radius tokens. - [ ] primitives: Button, Pressable, TextInput, Card, Surface, Toast, BottomSheet, ListItem. - [ ] dark mode + system-default theme switching. Phase 3 - Authentication (Effort: Medium) Dependencies: Phase 1. [ ] Firebase Auth: - [ ] Google sign-in via `@react-native-google-signin/google-signin`. - [ ] Apple sign-in via `expo-apple-authentication` (required for iOS store submission when other social providers are present). - [ ] email-link sign-in via Firebase dynamic links (or App Links / Universal Links setup). - [ ] secure token storage using `expo-secure-store`. Potential gotchas: - [ ] Apple sign-in is mandatory on iOS if Google sign-in is offered; do not ship to TestFlight without it. Phase 4 - Data model and offline-first storage (Effort: Large) Dependencies: Phase 3. [ ] Firestore collections: - [ ] `users/{uid}` profile. - [ ] `users/{uid}/items/{itemId}` the placeholder entity. - [ ] `users/{uid}/syncCheckpoints/{deviceId}` last successful sync. [ ] Offline-first strategy: - [ ] use Firestore offline persistence as the primary local cache. - [ ] use `expo-sqlite` (or MMKV) for derived caches/larger data sets if the customer's entity requires it. - [ ] every mutation writes optimistically locally, then enqueues a Firestore write; conflicts use last-write-wins with a per-record version counter. [ ] Security rules: - [ ] strict per-uid scoping on every collection. Phase 5 - Tab-bar shell and core flows (Effort: Large) Dependencies: Phase 4. [ ] Screens: - [ ] Home (recent activity, quick add). - [ ] Add (full editor). - [ ] Library (list, search, filter). - [ ] Profile (sign-in info, settings link). - [ ] Settings (theme, notifications, data export, account delete, about). [ ] Deep links: - [ ] `ai-eng-utility://item/{itemId}` and `https:///item/{itemId}` both resolve to the item detail screen. Potential gotchas: - [ ] gesture conflicts between tab navigation and modal sheets are the single biggest source of mobile UX bugs; cover with a Maestro flow. Phase 6 - Push notifications and in-app updates (Effort: Medium) Dependencies: Phase 5. [ ] FCM: - [ ] register device token in `users/{uid}/devices/{deviceId}`. - [ ] `sendNotification` Cloud Function callable for testing. - [ ] notification preference toggles in Settings. [ ] In-app updates: - [ ] Expo Updates configured with an EAS Update channel per build profile. - [ ] mandatory-update prompt if the running runtime version is below minimum supported. Potential gotchas: - [ ] never push code that changes native modules through EAS Update; that requires a full store build. Phase 7 - Observability, security, accessibility (Effort: Medium) Dependencies: Phases 3-6. [ ] Crashlytics or Sentry wired up with sourcemaps uploaded on every build. [ ] App Check enforced on every callable. [ ] Accessibility: - [ ] every interactive element has an accessible label. - [ ] dynamic type respected on iOS and Android. - [ ] color contrast >= 4.5:1. Potential gotchas: - [ ] App Check on Android requires Play Integrity API setup; without it, callables silently fail in production. Document the setup steps in the customization handbook. Phase 8 - Privacy, data export, account deletion (Effort: Medium) Dependencies: Phase 4. [ ] Settings: - [ ] "Export my data" triggers a Cloud Function that builds a ZIP of the user's documents and returns a signed Cloud Storage URL. - [ ] "Delete my account" runs `deleteUserAccount` Cloud Function that deletes all user-owned documents, revokes tokens, and removes the Auth user. [ ] Store-listing requirements: - [ ] privacy policy URL configured in `app.json`. - [ ] App Privacy questionnaire (iOS) and Data Safety form (Android) answers documented in `docs/store-listing.md`. Phase 9 - Performance budgets (Effort: Medium) Dependencies: Phases 5-7. [ ] Budgets: - [ ] cold start < 2.5s on a mid-range device. - [ ] APK/AAB size < 25MB (excluding assets the customer adds). - [ ] JS bundle size < 4MB. - [ ] memory at idle < 120MB. [ ] Asset rules: - [ ] all images bundled or fetched on demand via `expo-image` with a disk cache. - [ ] no fonts > 1MB. Phase 10 - Testing strategy (Effort: Medium) Dependencies: Phases 3-9. [ ] Vitest unit tests on every utility and Cloud Function. [ ] Firestore Security Rules tests for per-uid scoping. [ ] Maestro (or Detox) E2E happy path: sign in, create item, see it in Library, sign out, sign back in, item still present. Phase 11 - Customization handbook (Effort: Small per customer) Dependencies: Phases 0-10. [ ] `docs/customization.md` records, per customer: - [ ] app name, bundle ID/applicationId, icons, splash, primary color, typography. - [ ] real primary entity (replacing `items`). - [ ] sign-in providers enabled. - [ ] notification categories. - [ ] which tabs are added/removed/renamed. - [ ] store-listing copy, screenshots plan, App Privacy and Data Safety answers. - [ ] minimum supported OS versions and devices. Potential gotchas: - [ ] adding native modules later forces a new store build; document any native addition explicitly so the customer knows the deployment cost. Phase 12 - Public showcase integration (Effort: Small) Dependencies: this plan, ecosystem Phase 26. [ ] Register in `apps/web/src/lib/showcase.ts` with id `mobile-utility-app`. [ ] Live preview options for the marketing site: - [ ] PRIMARY: Appetize.io embedded iframe with a per-visitor short-lived session token issued through `getShowcasePrototypeSession` Cloud Function. The Appetize publicKey is NEVER shipped to the browser. - [ ] SECONDARY: a 90-second video walkthrough hosted in Cloud Storage as a fallback for visitors who block iframes or are on data-saving mode. [ ] Source visibility: - [ ] template README, architecture diagram, and the customization handbook table of contents surfaced on the detail page. Potential gotchas: - [ ] Appetize.io minutes burn fast on a popular showcase page; rate-limit session creation per visitor IP and prefer the video fallback for bots.