§1Overview

Rosie AI is a Flutter app for keeping personal memories — journaling, photo albums, an AI chat ("Rosie"), and people connections. Package com.bandraroad.heyrosie on Android, com.bandraroad.rosieai on iOS.

Architecture at a glance

§2Screenshot → APK workflow

The intended headline workflow. Drop a screenshot + describe the bug, get back a working APK.

The contract

The 7 steps

1. Read the screenshot — identify the screen, match it to a Dart file under AppCode/lib/features/
2. Locate the code — open the widget + its provider + relevant constants
3. State the bug in one sentence — if you can't, you don't understand it yet
4. Fix — minimal change, matching existing patterns. No drive-by refactors.
5. Verify it compiles: flutter analyze must pass
6. Build the APK: flutter build apk --debug, copy to timestamped slot
7. Report back in 3–5 lines

Trigger phrases

Any of these enters the workflow: "fix this", "ship a build", "fix and build", "do this", or any image with a problem description.

Install on the emulator

# JDK 17 required — Gradle 8.9 rejects JDK 26
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

adb -s emulator-5554 install -r \
  Frontend-Plan/builds/app-debug-<timestamp>.apk

# Launch:
adb -s emulator-5554 shell am start -n com.bandraroad.heyrosie/.MainActivity

§3Build & run

# All commands run from AppCode/
cd /Users/gauravtewari/PycharmProjects/AutomatedTestingApp/AppCode

# JDK 17 — REQUIRED. System default JDK 26 will fail.
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH=$JAVA_HOME/bin:$PATH

flutter pub get
flutter analyze
flutter test                              # unit + widget
flutter test integration_test/            # on a device/emulator

# Run on the project's emulator (rosie_proper / emulator-5554):
flutter run -d emulator-5554

# Build debug APK:
flutter build apk --debug
# Output: build/app/outputs/flutter-apk/app-debug.apk

# MobX codegen (after editing observables):
dart run build_runner build --delete-conflicting-outputs

§4Entry & app shell

Startup sequence (lib/main.dart)

1. WidgetsFlutterBinding.ensureInitialized()
2. IntentHandler.handleIntent() — incoming Android intents / deep links
3. setupLocator() — GetIt DI container (lib/core/di/locator.dart)
4. Firebase.initializeApp() with platform options (rosie-main project)
5. Firestore offline persistence + unlimited cache (Samsung-device quirk noted in code)
6. initializeApp() — NotificationService, RemoteConfigService, PhotoCacheService, AnalyticsService
7. OneSignal init (lines 138–303 in main.dart) with deep-link router

Root widget

MyApp (line 325 in main.dart) wraps everything with:

• MultiProvider — 20 ChangeNotifierProviders (see state management)
• FeatureDiscovery + ShowCaseWidget for tutorials
• MaterialApp with navigatorKey, themes, onGenerateRoute, analytics observer

Theme

Driven by MobX themeStore (lib/features/settings/theme_store.dart), observed in MyApp.build. Light/dark/system modes.

Startup sequence

§5State management

provider + ChangeNotifier for app state, MobX for theme only, GetIt for service singletons. No Riverpod, no Bloc.

Global providers

Consumption patterns

// Read once (no rebuild):
context.read<JournalProvider>().fetchEntries();

// Listen & rebuild on change:
final entries = context.watch<JournalProvider>().entries;

// Outside a widget (e.g. from a service callback):
Provider.of<JournalProvider>(
  navigatorKey.currentContext!, listen: false,
);

DI (GetIt)

// lib/core/di/locator.dart
locator.registerSingleton<FirebaseService>(FirebaseService());
locator.registerSingleton<NotificationService>(NotificationService());
locator.registerLazySingleton(() => UserProfileService());
locator.registerLazySingleton(() => BiometricAuthService());

State flow: a typical user action

Example: user taps "save" on a journal entry.

§6Routing & navigation

Navigator 1.0 with named routes via onGenerateRoute. Router lives at lib/core/navigation/app_router.dart. Not GoRouter.

Deep linking

OneSignal payload keys memoryId, deepLink, route are translated to navigator pushes in main.dart:216–290.

Programmatic navigation

final navigatorKey = GlobalKey<NavigatorState>();
navigatorKey.currentState?.pushNamed('/home');

Navigation map

§7Feature modules

Each feature in lib/features/ follows the same shape: screens/, provider/, models/, services/, widgets/.

Example: journal feature layout

features/journal/
├── journal_page.dart              // main screen
├── models/
│   ├── journal_model.dart
│   ├── journal_content_model.dart
│   └── focus_item_model.dart
├── provider/
│   ├── journal_provider.dart      // CRUD, AI summaries
│   └── journal_cart_provider.dart // drafts
├── services/
│   ├── journal_api.dart
│   ├── journal_data_service.dart
│   └── journal_firebase_service.dart
└── widgets/                       // notes, prompts, voice input

Feature module shape

Every feature in lib/features/<name>/ follows this internal structure.

§8Core services

lib/core/services/ holds the cross-cutting singletons and API wrappers used app-wide.

Services index

Local database

cache_manager_sqflite.dart in lib/core/database/ — SQLite via sqflite v2.4.1. Backs journal entries, notes, offline sync.

Environment switching

// lib/core/config/api_urls.dart
enum ApiEnvironment { production, staging }

class ApiUrls {
  static ApiEnvironment _currentEnvironment = ApiEnvironment.staging;

  static setEnvironment(ApiEnvironment env) =>
      _currentEnvironment = env;
}

No rebuild needed to flip — call ApiUrls.setEnvironment(...) at runtime.

§9Shared widgets

Cross-cutting UI lives in lib/widgets/ and lib/core/widgets/.

§10Backend integration

Firebase (rosie-main)

• Auth — email, Google, Apple, Facebook, phone
• Firestore — users/{uid}, memories/{id}, journals/{uid}/entries/{id}, connections/{uid}/connections/{id}, notes/{id}
• Storage — photos & videos
• Analytics — consent-gated; tracks appOpened, appForegrounded, appBackgrounded, route changes
• Remote Config — feature flags / env
• App Check enabled

REST APIs

Endpoints centralised in lib/core/config/api_urls.dart. Categories: chat, journal, memory, connection, profile. Auth via Firebase ID tokens in headers. http package v1.3.0. SQLite fallback for offline.

OneSignal push

• App ID 0adc76ab-1f0f-43f7-9b3f-1121eb197997 — hardcoded in main.dart:139 (see backlog)
• Player ID stored on the Firestore user doc
• Deep-link payload keys: memoryId, deepLink, route

Real-time

socket_io_client v3.0.0 — used for real-time notifications & chat.

Third-party integrations

Google Photos · Google Calendar (+ Calendly) · Spotify · WhatsApp · Facebook · Apple Sign-In.

§11Build & tooling

Android

• Namespace: com.bandraroad.heyrosie
• minSdk 24, targetSdk 36
• android/app/build.gradle version: 1.0.23 / 446 — drifts from pubspec.yaml 1.0.16+439. Reconcile before release.
• Signing via android/key.properties (not in repo)
• Google Services + Firebase plugins, Kotlin, Java 8 desugaring

iOS

• Bundle ID: com.bandraroad.rosieai
• Display name: heyRosie AI / heyrosie
• Info.plist permissions: camera, photos, microphone, location, calendar

Linting

flutter_lints enabled in analysis_options.yaml. prefer_const_constructors is intentionally disabled — flipping it on requires a project-wide cleanup; do not do in a single PR.

Codegen

build_runner ^2.4.13 + mobx_codegen ^2.6.2 (theme observables).

Assets

assets/{fonts,svgs,images,data,chatscreen}/ — fonts include Inter, Geist, serif variants.

CI/CD

No GitHub Actions present. Builds are manual. Adding lint + tests + build per PR is on the backlog.

§12Testing

Coverage is intentionally light — the AI testing harness in /test_runner does the heavy E2E lifting.

test/
├── unit/
│   ├── authentication_provider_test.dart  // pure error-mapping logic
│   ├── api_urls_test.dart                 // env switching
│   └── journal_api_test.dart
├── widget/
│   ├── dashboard_navigation_test.dart
│   ├── splash_screen_test.dart
│   └── screenshot_test.dart
├── collaborator_service_test.dart
└── widget_test.dart

integration_test/
├── app_flow_test.dart                     // captures screenshots
└── real_app_test.dart                     // full flow with Firebase

§13Conventions

• Classes PascalCase · files snake_case · vars/fns camelCase
• Feature-folder layout: screens / provider / models / services / widgets
• Public APIs use /// doc comments. Otherwise minimal comments.
• Some index.dart files act as barrel exports (e.g. lib/widgets/index.dart)
• Provider consumption: context.read<T>() / context.watch<T>() / Provider.of<T>(context, listen: false)

§14Known gotchas

§15Tech debt & backlog

Surfaced from the architecture audit. Source of truth lives in Frontend-Plan/backlog.md — this section mirrors it for reference.

§16Investor / mentor Q&A

Likely questions from investors and engineering mentors, with honest answers framed for credibility. Source of truth: Frontend-Plan/talking-points.md — edit there.

Architecture & technical choices

Q · Why Flutter and not native iOS + Android?

• One codebase, two platforms. A small team would otherwise need an iOS dev + an Android dev or accept being on one platform for 6–12 months longer.
• Performance is native-grade for a content-driven app like ours (no heavy 3D, no AR).
• Flutter is Google-backed — production at BMW, eBay, Alibaba, Google Pay.
• Trade-off, honestly: Flutter adds 8–12 MB to install size vs. pure native, and some niche native SDKs are slower to integrate. Neither has bitten us.

Q · Walk me through how the app is structured.

1. UI — lib/features/ has one folder per feature (journal, memory builder, chat, …). Self-contained.
2. State management — Provider pattern. Each feature has one or two "Providers" holding its data; UI rebuilds when data changes.
3. Services — lib/core/services/ is the only layer that talks to Firebase, our REST APIs, or the local cache. UI never touches the network directly.

Visual: architecture diagram, §1.

Q · Why Provider for state, not Riverpod or Bloc?

• Provider is the official Flutter team recommendation — the safest pick.
• Riverpod is newer and arguably better but the migration cost wasn't worth it.
• Bloc is heavier — designed for very large teams with strict separation of concerns. Overkill for our size.
• Honest gap: two providers grew too large and mix UI state with data. Logged on the backlog; not user-facing.

Q · What database do you use?

• Firestore (Google's NoSQL DB) for shared user data: profiles, memories, journals, connections.
• SQLite on-device for offline cache — app stays usable on a flight.
• Firebase Storage for photos and videos.
• No SQL/Postgres anywhere. Firestore gives us real-time sync, offline support, and authentication for free.

Q · How does authentication work?

Firebase Auth — email/password, Google, Apple, or Facebook. Sessions persisted. Firebase ID tokens (signed by Google) used when talking to our own backend. No passwords ever touch our servers.

Velocity & team productivity

Q · How fast can you ship a UI change?

• Small new screen: half a day to a day.
• Multi-screen feature (e.g. the memory-sharing flow): 2–5 days.
• Small visual bug fix to debug APK: target 15–30 minutes via a designed "screenshot → APK" workflow (§2).

Q · How do you know a build is safe to ship?

1. flutter analyze — static analysis on every build
2. Unit and widget tests for the riskiest pure logic (auth, API config, journaling)
3. AI testing harness — separate system that runs the real APK on a real Android emulator and uses GPT-4o vision to navigate the UI like a user would

Honest gap: frontend unit-test coverage is intentionally light — we offloaded broad coverage to the E2E harness because it's more representative. Trade-off is a slower feedback loop. CI pipeline that runs both layers per PR is on the roadmap.

Q · How big is the engineering team?

Frontend is currently a single developer + AI-assisted coding (Claude Code). Architecture and tooling are explicitly set up so a second developer can onboard in a day — top-level handoff doc plus per-folder CLAUDE.md conventions.

Scalability & cost

Q · Will this scale to a million users?

• Flutter scales linearly — the app runs on the user's device, so each new user is "free" from a compute perspective.
• Firestore scales horizontally to billions of documents; pricing scales predictably with reads / writes / storage.
• Hot spots to watch: photo uploads (Storage egress is the largest variable cost), Firestore reads on feeds (we cache aggressively).
• What we'd change at scale: a Redis-style read-side cache in front of Firestore for the hottest queries. Today we don't need it.

Q · What's the riskiest dependency?

• Firebase (Google) — Firestore and Auth are very mature; risk is low.
• OneSignal (push) — easily swappable for FCM.
• socket.io for real-time — could swap for Firestore listeners.
• No single-vendor "if they go down we're out of business" dependency other than Google itself.

Q · What if Google raises Firebase prices?

Firestore reads / writes are individually cheap; meaningful cost is storage at scale. Migration to self-hosted Postgres + S3 is a 6–8 week project if ever forced — not painless, not existential. Today, costs are well under $200/month all-in.

Quality & maintainability

Q · What's the worst part of the codebase right now?

Three honest items, all tracked in §15 backlog:

1. Two providers (JournalProvider, MemoryBuilderProvider) are too large and mix concerns. Refactor is scoped.
2. No CI pipeline yet — builds are manual. Test scripts exist; need to wire them into GitHub Actions.
3. Version-number drift between pubspec.yaml and the Android Gradle config. Cosmetic but should pick a source of truth before the first App Store release.

None are user-facing or block shipping.

Q · What happens when this developer gets hit by a bus?

• Full architecture documented in architecture.md and this HTML doc.
• Every Flutter session loads an AppCode/CLAUDE.md encoding the rules.
• A new Flutter dev (or another AI assistant) can be productive day one.
• A proposed screenshot → APK workflow (designed, prototype-validated) is intended to let non-engineers request fixes; once in daily use it further lowers the bus-factor risk.

Q · How are user-reported bugs handled?

Today: standard developer triage — Slack/email → repro → fix → next release. Nothing unusual.

Proposed (in design, not yet daily-use): the screenshot → APK workflow (§2) lets a non-engineer drop a screenshot + one sentence and produces a debug APK in 15–30 minutes. Validated once end-to-end; not yet the default for incoming bugs.

Production releases follow normal cadence (TestFlight / Play Store internal → external).

Security & privacy

Q · How is user data protected?

• In transit: HTTPS everywhere; Firebase ID tokens for our APIs.
• At rest: Firestore + Firebase Storage encrypted by Google.
• On device: Firebase Auth tokens, biometric unlock supported.
• Analytics consent-gated — we don't track without permission.
• App Check enabled — Firebase rejects requests from non-genuine app installs.
• No raw passwords on our infrastructure (Firebase Auth handles it).

Roadmap (frontend angle)

Q · What's the next major frontend investment?

1. Biographer feature — currently a "coming soon" stub. Voice + text life-story capture.
2. CI pipeline — automated lint + test + build per PR.
3. Provider refactor — split the two large ones; cleaner foundation for new contributors.
4. iOS-side polish — Flutter handles both platforms but iOS-specific UX touches (haptics, dynamic type) deserve a pass before App Store launch.

Q · What can the frontend NOT do today that you wish it could?

• Real-time collaborative memory editing — architecturally possible (socket.io is in place) but no UI yet.
• Rich text editing in journal (today it's mostly plain text + attachments).
• Native-feeling iOS scroll physics in some screens.

§17Quick reference

Where things live

Companion documents

• Frontend-Plan/README.md — folder map & workflows
• Frontend-Plan/workflow.md — full screenshot → APK playbook
• Frontend-Plan/architecture.md — markdown mirror of this doc
• Frontend-Plan/backlog.md — open work (source of truth)
• Frontend-Plan/talking-points.md — investor & mentor Q&A (editable source)
• AppCode/CLAUDE.md — rules every Claude session loads when working in AppCode/