VibeKB Stoppr

Generated output — this is a static snapshot rendered from .vibekb/. The .vibekb/ content is the source of truth. See Reference for provenance.

Diagrams

Diagrams

Source-grounded visual maps of what the software is doing. Each diagram explains what you are seeing, how it was verified, and what remains uncertain — and links back to the functionality and warnings it relates to.

Diagrams never claim behaviour that has not been traced to source. Inferred or unverified paths are labelled in the diagram itself.

Understand the whole app

Fast visual entry points for Stoppr.

Stoppr application overview

How the Flutter client relates to Firebase, purchases, local state, and external AI/food APIs.

Stoppr application overview The Flutter client depends on Firebase for identity and data, on RevenueCat and Superwall for paid access, on local preferences and widgets for daily state, and on external AI or food APIs for scanning, chatbot, and recipes. An inferred edge shows purchase status mirrored into Firestore. Stoppr application overview Solid = verified from source · Dashed = inferred. Select a box or arrow for its explanation. Stoppr mobile client — open explanation Stoppr mobile client Flutter iOS / Android Firebase — open explanation Firebase Auth · Firestore · FCM RevenueCat + Superwall — open explanation RevenueCat + Superwall Paid access source of truth Local device state — open explanation Local device state Prefs · widgets External AI / food APIs — open explanation External AI / food APIs Groq · OpenAI · recipes depends on Firebase — verified depends-on depends on purchases — verified depends-on stores in local state — verified stores-in sends to external APIs — verified sends-to writes mirror fields — inferred writes (inferred)
What am I looking at? How the Flutter client relates to Firebase, purchases, local state, and external AI/food APIs.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

Stoppr mobile client
Verified from source

Flutter iOS/Android app the user installs and opens.

Related functionality: Application startup

Where it lives lib//
  • lib/
    • main.dart
Files that implement or support it
  • Entry pointlib/main.dart

    Cold-start bootstrap and first navigation decisions.

    Canonical purpose: Cold-start bootstrap: dotenv, RevenueCat, Firebase, analytics, notifications, Superwall, deep links, and startup routing into onboarding, paywall, or MainScaffold.

    Open entry point

Firebase
Verified from source

Auth identity, Firestore documents, Storage, Messaging, Crashlytics.

Related functionality: Firebase authentication Calorie nutrition tracking

Where it lives cloud/
  • lib/
    • firebase_options.dart
Files that implement or support it
  • Configurationlib/firebase_options.dart

    Builds FirebaseOptions from EnvConfig key names.

    Canonical purpose: Env-backed DefaultFirebaseOptions for Android/iOS only; missing keys assert at startup.

    View configuration

RevenueCat + Superwall
Verified from source

Store purchases and paywall presentation that decide premium access.

Related functionality: Subscription access gating Main paywall

Where it lives lib/core/subscription, lib/core/superwall/
  • lib/
    • core/
      • subscription/
        • subscription_service.dart
      • superwall/
        • superwall_purchase_controller.dart
Files that implement or support it
  • Primary implementationlib/core/subscription/subscription_service.dart

    isPaidSubscriber decides access from Superwall/RevenueCat.

    Canonical purpose: Paid-access decisions from Superwall subscription status and RevenueCat CustomerInfo. Firestore subscription fields are not the entitlement source of truth.

    Open implementation

  • Integration adapterlib/core/superwall/superwall_purchase_controller.dart

    Maps Superwall purchase requests onto RevenueCat.

    Canonical purpose: Maps Superwall purchase/restore actions to RevenueCat and syncs subscription status back to Superwall.

    View source on GitHub

Local device state
Verified from source

SharedPreferences, HomeWidget bridge, and local caches for fast daily loops.

Related functionality: Sugar streak tracking Home screen widgets

Where it lives device/
  • lib/
    • core/
      • streak/
        • streak_service.dart
Files that implement or support it
  • Primary implementationlib/core/streak/streak_service.dart

    Writes streak values locally and to the widget bridge.

    Canonical purpose: Streak persistence (SharedPreferences + Firestore) and home_widget sync. iOS app group id is still group.YOUR_BUNDLE_ID.shared.

    Open implementation

External AI / food APIs
Verified from source

Groq, OpenAI, Edamam, and Spoonacular called for scanning, chatbot, and recipes.

Related functionality: Sugar food scanning Melinda chatbot assistant Recipe discovery

Where it lives external/
  • lib/
    • core/
      • config/
        • env_config.dart
Files that implement or support it
  • Configurationlib/core/config/env_config.dart

    Exposes API key environment variable names used by those features.

    Canonical purpose: Typed accessors for environment variable NAMES used by Firebase, purchases, AI, and analytics. Never commit values.

    View configuration

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

Stoppr mobile client depends on Firebase
Verified from source Solid line

The client authenticates users and reads/writes profile, onboarding, community, and nutrition documents through Firebase SDKs.

Related functionality: Firebase authentication

Files behind this connection
  • Callerlib/core/auth/auth_service.dart

    Performs Firebase Auth sign-in and profile side effects.

    Canonical purpose: Firebase Auth (Google, Apple, email) plus RevenueCat/Mixpanel identity sync and users/{uid} profile writes. Google OAuth fallbacks are placeholders when env is missing.

    View caller

Stoppr mobile client depends on RevenueCat + Superwall
Verified from source Solid line

Startup routing and feature gates call SubscriptionService / Superwall to know whether the user is paid.

Related functionality: Subscription access gating

Files behind this connection
  • Calleelib/core/subscription/subscription_service.dart

    Returns paid/free based on Superwall and RevenueCat.

    Canonical purpose: Paid-access decisions from Superwall subscription status and RevenueCat CustomerInfo. Firestore subscription fields are not the entitlement source of truth.

    View callee

Stoppr mobile client stores in Local device state
Verified from source Solid line

Daily habit state such as streaks and onboarding progress is stored on-device and mirrored to widgets.

Related functionality: Sugar streak tracking Startup routing

Files behind this connection
  • Primary implementationlib/features/onboarding/data/services/onboarding_progress_service.dart

    Persists onboarding resume keys in SharedPreferences.

    Canonical purpose: SharedPreferences + Firestore resume checkpoints and onboarding_completed for startup routing.

    Open implementation

Stoppr mobile client sends to External AI / food APIs
Verified from source Solid line

Food scan, Rate My Plate, chatbot, and recipe search send requests to configured external APIs.

Related functionality: Sugar food scanning Melinda chatbot assistant Recipe discovery

Files behind this connection
  • Callerlib/features/app/presentation/screens/chatbot/chatbot_screen.dart

    Issues Groq/OpenAI requests for Melinda responses.

    Canonical purpose: Melinda CBT assistant using Groq chat/transcription and OpenAI speech, with daily API interaction limits.

    View caller

RevenueCat + Superwall writes Firebase
Inferred from source Dashed line

After purchase sync, subscription mirror fields are written to the user Firestore document for analytics/display.

Basis for the inference: Purchase controller contains Firestore update helpers traced at class level; every write site was not line-enumerated.

Related functionality: Main paywall

Files behind this connection
  • Callerlib/core/superwall/superwall_purchase_controller.dart

    Persists subscription mirror fields after RevenueCat sync.

    Canonical purpose: Maps Superwall purchase/restore actions to RevenueCat and syncs subscription status back to Superwall.

    View caller

Uncertain: Exact field set per product type not exhaustively listed.

Diagram type
Application overview
Verification
Verified from source
Source evidence
Traced lib/main.dart, auth, subscription, streak, and env_config against source at analysis commit.
Last verified against source
2026-07-21
Uncertainty
Firestore mirror field completeness after purchase is inferred; store dashboard config not verified.

Related functionality: Application startup Firebase authentication Subscription access gating Sugar streak tracking Melinda chatbot assistant

Related warnings: Placeholder API keys and OAuth client IDs

Related diagrams: Onboarding and authentication flow Subscription and paywall flow

Understand the main product flows

Onboarding, auth, and subscription paths.

Onboarding and authentication flow

Welcome to auth to questionnaire/profile to pre-paywall to MainScaffold.

Onboarding and authentication flow Users move from welcome screens through auth providers, questionnaire and profile personalization, the Superwall pre-paywall, and into MainScaffold. One dashed edge marks funnel ordering inferred across Navigator calls. Onboarding and authentication flow Solid = verified · Dashed = inferred funnel ordering. Select any element for details. Welcome + early onboarding — open explanation Welcome intro screens Auth providers — open explanation Auth providers Google/Apple/email/anon Questionnaire + profile — open explanation Questionnaire profile · goals · analysis Pre-paywall — open explanation Pre-paywall Superwall gate MainScaffold — open explanation MainScaffold app shell routes to auth — verified routes-to routes to questionnaire — inferred routes-to (inferred) routes to paywall — verified routes-to routes to main — verified routes-to
What am I looking at? Welcome to auth to questionnaire/profile to pre-paywall to MainScaffold.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

Welcome + early onboarding
Verified from source

Plays welcome video and early intro screens that offer auth or skip.

Related functionality: Onboarding introduction

Where it lives lib/features/onboarding/presentation/screens/
  • lib/
    • features/
      • onboarding/
        • presentation/
          • screens/
            • welcome_video_screen.dart
Files that implement or support it
  • Entry pointlib/features/onboarding/presentation/screens/welcome_video_screen.dart

    First visible onboarding surface after splash routing.

    Open entry point

Auth providers
Verified from source

Google, Apple, email, or anonymous Firebase sign-in creating an AppUser.

Related functionality: Firebase authentication Guest anonymous access

Where it lives lib/core/auth/
  • lib/
    • core/
      • auth/
        • auth_service.dart
Files that implement or support it
  • Primary implementationlib/core/auth/auth_service.dart

    Implements provider sign-in methods and auth state listener.

    Canonical purpose: Firebase Auth (Google, Apple, email) plus RevenueCat/Mixpanel identity sync and users/{uid} profile writes. Google OAuth fallbacks are placeholders when env is missing.

    Open implementation

Questionnaire + profile
Verified from source

Collects questionnaire answers, profile, symptoms, goals, and nutrition setup with resume checkpoints.

Related functionality: Onboarding questionnaire Onboarding profile and goals Onboarding personalized analysis

Where it lives lib/features/onboarding/
  • lib/
    • features/
      • onboarding/
        • data/
          • services/
            • onboarding_progress_service.dart
Files that implement or support it
  • Primary implementationlib/features/onboarding/data/services/onboarding_progress_service.dart

    Persists and restores the current onboarding screen.

    Canonical purpose: SharedPreferences + Firestore resume checkpoints and onboarding_completed for startup routing.

    Open implementation

Pre-paywall
Verified from source

Final commercial gate before MainScaffold for unpaid users.

Related functionality: Main paywall

Where it lives lib/features/onboarding/presentation/screens/
  • lib/
    • features/
      • onboarding/
        • presentation/
          • screens/
            • pre_paywall.dart
Files that implement or support it
  • Primary implementationlib/features/onboarding/presentation/screens/pre_paywall.dart

    Registers Superwall placements and handles purchase success.

    Canonical purpose: Primary paywall UI and Superwall placement registration. Many placement IDs remain INSERT_YOUR_* placeholders.

    Open implementation

MainScaffold
Verified from source

Post-onboarding app shell with bottom navigation.

Related functionality: Main navigation

Where it lives lib/features/app/presentation/screens/
  • lib/
    • features/
      • app/
        • presentation/
          • screens/
            • main_scaffold.dart
Files that implement or support it
  • Primary implementationlib/features/app/presentation/screens/main_scaffold.dart

    Hosts the signed-in / paid user experience.

    Canonical purpose: Bottom-tab shell hosting Home, Learn, Rewire, Community, and Profile with initialIndex deep-link entry.

    Open implementation

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

Welcome + early onboarding routes to Auth providers
Verified from source Solid line

Early onboarding screens route the user into Google/Apple/email sign-in or allow skipping toward later anonymous creation.

Related functionality: Onboarding introduction Firebase authentication

Files behind this connection
  • Callerlib/features/onboarding/presentation/screens/onboarding_page.dart

    Invokes AuthCubit Google/Apple sign-in handlers.

    View caller

Auth providers routes to Questionnaire + profile
Inferred from source Dashed line

After identity exists (or skip), navigation continues into questionnaire, profile, and personalization screens.

Basis for the inference: Order derived from Navigator calls across onboarding screens rather than one central route table.

Related functionality: Onboarding questionnaire

Files behind this connection
  • Primary implementationlib/features/onboarding/presentation/screens/questionnaire_screen.dart

    Collects and persists questionnaire answers.

    Open implementation

Uncertain: Exact branch when questionnaire answers are missing uses a shorter path.

Questionnaire + profile routes to Pre-paywall
Verified from source Solid line

Completed personalization and benefits screens navigate to PrePaywallScreen.

Related functionality: Main paywall

Files behind this connection
  • Calleelib/features/onboarding/presentation/screens/pre_paywall.dart

    Receives users at the commercial gate.

    Canonical purpose: Primary paywall UI and Superwall placement registration. Many placement IDs remain INSERT_YOUR_* placeholders.

    View callee

Pre-paywall routes to MainScaffold
Verified from source Solid line

Successful purchase handling or an already-paid check navigates to MainScaffold.

Related functionality: Main paywall Main navigation

Files behind this connection
  • Callerlib/core/subscription/post_purchase_handler.dart

    Runs post-purchase updates then navigates onward.

    View caller

Diagram type
Authentication flow
Verification
Inferred from source
Source evidence
Screens and AuthService traced; multi-file Navigator order partially inferred.
Last verified against source
2026-07-21
Uncertainty
Resume branches and skip paths create alternate orders not fully drawn.

Related functionality: Onboarding introduction Firebase authentication Onboarding questionnaire Main paywall Main navigation

Related warnings: Google OAuth client ID fallbacks

Related diagrams: Stoppr application overview Subscription and paywall flow

Subscription and paywall flow

Superwall UI to purchase controller to RevenueCat to access gate, with post-purchase handling.

Subscription and paywall flow Superwall UI delegates purchases to SuperwallPurchaseController, which calls RevenueCat. SubscriptionService gates access from CustomerInfo and Superwall status. PostPurchaseHandler runs success side effects. Dashed edges mark Android wiring risk and multi-file success orchestration. Subscription and paywall flow Dashed edges mark platform-dependent or multi-file success orchestration. Superwall paywall UI — open explanation Superwall UI placements SuperwallPurchaseController — open explanation PurchaseController RC bridge RevenueCat — open explanation RevenueCat CustomerInfo SubscriptionService gate — open explanation Access gate isPaidSubscriber PostPurchaseHandler — open explanation PostPurchaseHandler side effects + nav delegates to controller — inferred delegates-to (inferred) calls RevenueCat — verified calls returns CustomerInfo — verified returns-to emits success path — inferred emits (inferred)
What am I looking at? Superwall UI to purchase controller to RevenueCat to access gate, with post-purchase handling.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

Superwall paywall UI
Verified from source

Presents campaigns registered by placement IDs from PrePaywall and feature screens.

Related functionality: Main paywall Soft paywalls and quotas

Where it lives lib/features/onboarding, lib/features/app/
  • lib/
    • features/
      • onboarding/
        • presentation/
          • screens/
            • pre_paywall.dart
Files that implement or support it
  • Callerlib/features/onboarding/presentation/screens/pre_paywall.dart

    Registers primary gift/standard placements (often placeholders).

    Canonical purpose: Primary paywall UI and Superwall placement registration. Many placement IDs remain INSERT_YOUR_* placeholders.

    View caller

Uncertain: Dashboard campaign mapping not verified.

SuperwallPurchaseController
Verified from source

Receives Superwall purchase/restore requests and executes them via RevenueCat.

Related functionality: Subscription access gating

Where it lives lib/core/superwall/
  • lib/
    • core/
      • superwall/
        • superwall_purchase_controller.dart
Files that implement or support it
  • Primary implementationlib/core/superwall/superwall_purchase_controller.dart

    Implements PurchaseController purchase/restore and status sync.

    Canonical purpose: Maps Superwall purchase/restore actions to RevenueCat and syncs subscription status back to Superwall.

    Open implementation

RevenueCat
Verified from source

Talks to App Store / Play Billing and exposes CustomerInfo entitlements.

Related functionality: Subscription access gating

Where it lives purchases_flutter/
  • lib/
    • main.dart
Files that implement or support it
  • Entry pointlib/main.dart

    Early Purchases.configure using platform API key names.

    Canonical purpose: Cold-start bootstrap: dotenv, RevenueCat, Firebase, analytics, notifications, Superwall, deep links, and startup routing into onboarding, paywall, or MainScaffold.

    Open entry point

SubscriptionService gate
Verified from source

Answers isPaidSubscriber for routing and feature checks.

Related functionality: Subscription access gating Startup routing

Where it lives lib/core/subscription/
  • lib/
    • core/
      • subscription/
        • subscription_service.dart
Files that implement or support it
  • Primary implementationlib/core/subscription/subscription_service.dart

    Combines Superwall status and RevenueCat CustomerInfo; ignores Firestore for grants.

    Canonical purpose: Paid-access decisions from Superwall subscription status and RevenueCat CustomerInfo. Firestore subscription fields are not the entitlement source of truth.

    Open implementation

PostPurchaseHandler
Verified from source

After success, updates user state and navigates to congratulations / main.

Related functionality: Main paywall

Where it lives lib/core/subscription/
  • lib/
    • core/
      • subscription/
        • post_purchase_handler.dart
Files that implement or support it
  • Primary implementationlib/core/subscription/post_purchase_handler.dart

    Coordinates post-purchase side effects and navigation.

    Open implementation

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

Superwall paywall UI delegates to SuperwallPurchaseController
Inferred from source Dashed line

Superwall UI delegates store purchase and restore actions to SuperwallPurchaseController when configured.

Basis for the inference: iOS configure path passes purchaseController; Android early configure does not, so delegation is platform-dependent.

Related functionality: Main paywall

Files behind this connection
  • Calleelib/core/superwall/superwall_purchase_controller.dart

    Implements the PurchaseController callbacks Superwall invokes.

    Canonical purpose: Maps Superwall purchase/restore actions to RevenueCat and syncs subscription status back to Superwall.

    View callee

Uncertain: Android path may not attach the controller.

SuperwallPurchaseController calls RevenueCat
Verified from source Solid line

The controller calls RevenueCat product lookup, purchase, and restore APIs.

Related functionality: Subscription access gating

Files behind this connection
  • Callerlib/core/superwall/superwall_purchase_controller.dart

    Invokes Purchases.purchaseStoreProduct / restorePurchases.

    Canonical purpose: Maps Superwall purchase/restore actions to RevenueCat and syncs subscription status back to Superwall.

    View caller

RevenueCat returns to SubscriptionService gate
Verified from source Solid line

SubscriptionService reads CustomerInfo (and Superwall status) to decide paid access.

Related functionality: Subscription access gating

Files behind this connection
  • Calleelib/core/subscription/subscription_service.dart

    isPaidSubscriber inspects entitlements/subscriptions.

    Canonical purpose: Paid-access decisions from Superwall subscription status and RevenueCat CustomerInfo. Firestore subscription fields are not the entitlement source of truth.

    View callee

SuperwallPurchaseController emits PostPurchaseHandler
Inferred from source Dashed line

Paywall success handling invokes PostPurchaseHandler to finalize onboarding-side effects.

Basis for the inference: PrePaywall calls PostPurchaseHandler on success; controller sync also updates status — success orchestration spans both.

Related functionality: Main paywall

Files behind this connection
  • Calleelib/core/subscription/post_purchase_handler.dart

    handlePostPurchase runs after a successful purchase path.

    View callee

Uncertain: Exact ordering of Firestore writes vs navigation not single-step traced.

Diagram type
Feature access
Verification
Inferred from source
Source evidence
Classes traced; Android configure asymmetry and placement placeholders labeled.
Last verified against source
2026-07-21
Uncertainty
Store products and Superwall dashboard campaigns not executed.

Related functionality: Main paywall Subscription access gating Soft paywalls and quotas

Related warnings: Superwall placement IDs are placeholders Android Superwall purchase controller wiring is incomplete

Related diagrams: Stoppr application overview Onboarding and authentication flow

Understand the technical system

Where data and entitlements live.

Persistence and storage map

Feature writers to Firestore, SharedPreferences, HomeWidget, and Firebase Storage.

Persistence and storage map Feature repositories write to Firestore and SharedPreferences, push selected values through the HomeWidget bridge, and may upload food images to Firebase Storage. Dashed edges mark inferred native widget delivery and upload branching. Persistence and storage map Where Stoppr keeps state. Dashed = inferred native/widget delivery details. Feature repositories — open explanation Feature repositories domain writers Cloud Firestore — open explanation Cloud Firestore users · community SharedPreferences — open explanation SharedPreferences resume · streak · fast HomeWidget bridge — open explanation HomeWidget bridge iOS / Android widgets Firebase Storage — open explanation Firebase Storage food images writes Firestore — verified writes stores in prefs — verified stores-in sends to widgets — inferred sends-to (inferred) writes storage — inferred writes (inferred)
What am I looking at? Feature writers to Firestore, SharedPreferences, HomeWidget, and Firebase Storage.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

Feature repositories
Verified from source

Domain code that reads and writes user, community, nutrition, and challenge data.

Related functionality: Calorie nutrition tracking Community forum Twenty-eight day challenge

Where it lives lib/features, lib/core/
  • lib/
    • features/
      • nutrition/
        • data/
          • repositories/
            • nutrition_repository.dart
Files that implement or support it
  • Primary implementationlib/features/nutrition/data/repositories/nutrition_repository.dart

    Representative Firestore writer for food logs and goals.

    Canonical purpose: Nutrition Firestore hub for food_logs, daily_summaries, goals, body metrics, and workouts.

    Open implementation

Cloud Firestore
Verified from source

Primary shared database for users, community, accountability, and quotas.

Related functionality: Firebase authentication Community forum Accountability partners

Where it lives cloud/
  • firestore.rules
Files that implement or support it
  • Validationfirestore.rules

    Server-side rules governing client access to collections.

    Canonical purpose: Server-side Firestore access rules for users, community, accountability, and related collections.

    View source on GitHub

SharedPreferences
Verified from source

Fast local keys for onboarding resume, streaks, fasting, and notification prefs.

Related functionality: Startup routing Sugar streak tracking Fasting tracker

Where it lives device/
  • lib/
    • features/
      • onboarding/
        • data/
          • services/
            • onboarding_progress_service.dart
Files that implement or support it
  • Storagelib/features/onboarding/data/services/onboarding_progress_service.dart

    Owns onboarding_* preference keys used at startup.

    Canonical purpose: SharedPreferences + Firestore resume checkpoints and onboarding_completed for startup routing.

    View source on GitHub

HomeWidget bridge
Verified from source

Pushes selected values to iOS/Android home screen widgets.

Related functionality: Home screen widgets

Where it lives lib/core/streak, ios/StreakWidget, android providers/
  • lib/
    • core/
      • streak/
        • streak_service.dart
Files that implement or support it
  • Integration adapterlib/core/streak/streak_service.dart

    Sets app group id and updates widget data.

    Canonical purpose: Streak persistence (SharedPreferences + Firestore) and home_widget sync. iOS app group id is still group.YOUR_BUNDLE_ID.shared.

    View source on GitHub

Uncertain: App group placeholder blocks real iOS sync.

Firebase Storage
Verified from source

Optional remote store for food images via LocalFoodImageService.

Related functionality: Sugar food scanning

Where it lives cloud/
  • lib/
    • core/
      • services/
        • local_food_image_service.dart
Files that implement or support it
  • Primary implementationlib/core/services/local_food_image_service.dart

    Caches images locally and can upload/fallback to Storage.

    Open implementation

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

Feature repositories writes Cloud Firestore
Verified from source Solid line

Repositories write user, community, nutrition, and challenge documents to Firestore.

Related functionality: Calorie nutrition tracking Community forum

Files behind this connection
  • Callerlib/features/community/data/repositories/community_repository.dart

    Writes community_posts and comments.

    Canonical purpose: Community posts/comments Firestore repository for the forum surface.

    View caller

Feature repositories stores in SharedPreferences
Verified from source Solid line

Onboarding, streak, fasting, and similar features store resume/fast state in SharedPreferences.

Related functionality: Startup routing Fasting tracker

Files behind this connection
  • Callerlib/features/fasting/data/repositories/fasting_repository.dart

    Persists fasting_logs_v1 locally only.

    Canonical purpose: Local-only fasting logs and active timer cache in SharedPreferences.

    View caller

SharedPreferences sends to HomeWidget bridge
Inferred from source Dashed line

Streak and accountability services push values through HomeWidget into native widgets.

Basis for the inference: Flutter update calls verified; native Swift/Kotlin read path inferred from suiteName/providers.

Related functionality: Home screen widgets Sugar streak tracking

Files behind this connection
  • Callerlib/core/accountability/accountability_widget_service.dart

    Updates accountability widget payloads.

    View caller

Uncertain: Placeholder app group may prevent iOS delivery.

Feature repositories writes Firebase Storage
Inferred from source Dashed line

LocalFoodImageService can upload cached food images to Firebase Storage as a fallback/remote path.

Basis for the inference: Service responsibilities traced; every upload call site not enumerated.

Related functionality: Sugar food scanning

Files behind this connection
  • Callerlib/core/services/local_food_image_service.dart

    Implements upload/fallback for food images.

    View caller

Uncertain: When upload vs local-only is chosen may depend on runtime flags.

Diagram type
Storage map
Verification
Inferred from source
Source evidence
Repository write paths verified; widget native delivery inferred.
Last verified against source
2026-07-21
Uncertainty
App group placeholder may prevent iOS widget sync.

Related functionality: Calorie nutrition tracking Sugar streak tracking Home screen widgets Community forum

Related warnings: iOS widget app group ID is a placeholder

Related diagrams: Stoppr application overview

Understand uncertainty

Configuration landmines and unverified edges.

Risk and uncertainty map

Verified configuration landmines that can break auth, paywalls, widgets, or quota soft-gates.

Risk and uncertainty map Five verified configuration landmines: Superwall placement placeholders, Android Superwall purchase controller wiring, OAuth and env fallbacks, widget app group placeholder, and disabled quota flags. Two configures edges show how Android wiring and quota flags affect the placement-driven paywall path. Risk and uncertainty map Configuration landmines verified in source. Select a box for the warning and next action. Superwall placement placeholders — open explanation Placement placeholders INSERT_YOUR_* IDs Android Superwall wiring — open explanation Android SW wiring no purchaseController OAuth / env fallbacks — open explanation OAuth / env fallbacks .env vs .env.local Widget app group placeholder — open explanation Widget app group YOUR_BUNDLE_ID Disabled quota flags — open explanation Quota flags off QUOTA_SYSTEM_ENABLED configures purchase path — verified configures configures soft paywalls — verified configures
What am I looking at? Verified configuration landmines that can break auth, paywalls, widgets, or quota soft-gates.
How to read this Solid line — verified from source Dashed line — inferred from source Select any box or arrow in the diagram to jump to its explanation.

Parts — what each one is

Each part explains why it appears, where it lives in the repository, and which files to read.

Superwall placement placeholders
Verified from source

Many registerPlacement calls still use INSERT_YOUR_* strings instead of real IDs.

Related functionality: Main paywall Soft paywalls and quotas

Where it lives lib/features, lib/core/
  • lib/
    • features/
      • onboarding/
        • presentation/
          • screens/
            • pre_paywall.dart
Files that implement or support it
  • Primary implementationlib/features/onboarding/presentation/screens/pre_paywall.dart

    Contains primary INSERT_YOUR_* placement registrations.

    Canonical purpose: Primary paywall UI and Superwall placement registration. Many placement IDs remain INSERT_YOUR_* placeholders.

    Open implementation

⚠ Warnings: Superwall placement IDs are placeholders

Android Superwall wiring
Verified from source

Android configure path does not attach SuperwallPurchaseController like iOS.

Related functionality: Subscription access gating

Where it lives lib/main.dart/
  • lib/
    • main.dart
Files that implement or support it
  • Entry pointlib/main.dart

    Early Android Superwall.configure omits purchaseController.

    Canonical purpose: Cold-start bootstrap: dotenv, RevenueCat, Firebase, analytics, notifications, Superwall, deep links, and startup routing into onboarding, paywall, or MainScaffold.

    Open entry point

⚠ Warnings: Android Superwall purchase controller wiring is incomplete

Uncertain: Runtime purchase impact not executed.

OAuth / env fallbacks
Verified from source

Missing env values fall back to placeholder OAuth client IDs; main loads .env while repo has .env.local.

Related functionality: Firebase authentication Application startup

Where it lives lib/core/auth, lib/core/config/
  • lib/
    • core/
      • auth/
        • auth_service.dart
Files that implement or support it
  • Primary implementationlib/core/auth/auth_service.dart

    Embeds INSERT_YOUR_* Google client ID fallbacks.

    Canonical purpose: Firebase Auth (Google, Apple, email) plus RevenueCat/Mixpanel identity sync and users/{uid} profile writes. Google OAuth fallbacks are placeholders when env is missing.

    Open implementation

⚠ Warnings: Google OAuth client ID fallbacks Repository has .env.local but main loads .env

Widget app group placeholder
Verified from source

Home widgets reference group.YOUR_BUNDLE_ID.shared until a real group is configured.

Related functionality: Home screen widgets

Where it lives lib/core/streak, ios entitlements/
  • lib/
    • core/
      • streak/
        • streak_service.dart
Files that implement or support it
  • Configurationlib/core/streak/streak_service.dart

    Defines the placeholder app group constant.

    Canonical purpose: Streak persistence (SharedPreferences + Firestore) and home_widget sync. iOS app group id is still group.YOUR_BUNDLE_ID.shared.

    View configuration

⚠ Warnings: iOS widget app group ID is a placeholder

Disabled quota flags
Verified from source

FeatureQuota soft-paywalls exist but QUOTA_SYSTEM_ENABLED is false on major screens.

Related functionality: Soft paywalls and quotas

Where it lives feature screens/
  • lib/
    • features/
      • learn/
        • presentation/
          • screens/
            • learn_video_list_screen.dart
Files that implement or support it
  • Primary implementationlib/features/learn/presentation/screens/learn_video_list_screen.dart

    Hard-codes QUOTA_SYSTEM_ENABLED = false.

    Open implementation

Connections — why they connect

Each connection names the concrete mechanism linking its two parts. The mechanism is the proof the relationship passed the explainability gate.

Android Superwall wiring configures Superwall placement placeholders
Verified from source Solid line

Android Superwall configuration controls whether placement-driven purchases can reach SuperwallPurchaseController.

Related functionality: Main paywall Subscription access gating

Files behind this connection
  • Configurationlib/main.dart

    Platform branch decides whether purchaseController is passed to Superwall.configure.

    Canonical purpose: Cold-start bootstrap: dotenv, RevenueCat, Firebase, analytics, notifications, Superwall, deep links, and startup routing into onboarding, paywall, or MainScaffold.

    View configuration

Disabled quota flags configures Superwall placement placeholders
Verified from source Solid line

QUOTA_SYSTEM_ENABLED flags configure whether feature screens invoke quota checks that lead to soft Superwall placements.

Related functionality: Soft paywalls and quotas

Files behind this connection
  • Configurationlib/features/app/presentation/screens/chatbot/chatbot_screen.dart

    Local flag disables quota path before placement registration.

    Canonical purpose: Melinda CBT assistant using Groq chat/transcription and OpenAI speech, with daily API interaction limits.

    View configuration

Diagram type
Risk and uncertainty map
Verification
Verified from source
Source evidence
Each landmine grepped and file-traced in source.
Last verified against source
2026-07-21
Uncertainty
Runtime severity depends on private env and dashboard config not in git.

Related functionality: Main paywall Subscription access gating Firebase authentication Home screen widgets Soft paywalls and quotas

Related warnings: Superwall placement IDs are placeholders Android Superwall purchase controller wiring is incomplete Google OAuth client ID fallbacks iOS widget app group ID is a placeholder Repository has .env.local but main loads .env

Related diagrams: Subscription and paywall flow