Decisions & rationale

The reasoning behind the software

Decisions, constraints, assumptions, warnings, and discoveries — each connected to the functionality it explains. Repository memory supports the software model; it does not replace it.

Decisions

Imperative Navigator routing

Verified from source

Primary navigation uses Navigator push/replace rather than a single declarative router graph.

Startup routing Main navigation Deep link handling
RevenueCat/Superwall gate access, not Firestore

Verified from source

Paid access ignores Firestore subscription fields for granting entitlements.

Subscription access gating Startup routing

Constraints

Environment-driven secrets

API keys and OAuth clients come from dotenv / platform templates; values must not be committed or documented.

Application startup Firebase authentication
Mobile Flutter client

Stoppr ships as iOS/Android Flutter; VibeKB docs are static HTML, not part of the app binary.

Application startup

Assumptions

Onboarding health copy is marketing, not verified science

Not verified

UI claims about sugar/health are not validated by this software model.

Onboarding introduction Onboarding personalized analysis

Warnings

Android Superwall purchase controller wiring is incomplete

high Verified from source

Android early Superwall.configure does not pass SuperwallPurchaseController; later path returns early on Android.

Subscription access gating Main paywall
Repository has .env.local but main loads .env

medium Verified from source

Only .env.local is present in the tree while main.dart loads dotenv .env.

Application startup
Google OAuth client ID fallbacks

medium Verified from source

auth_service.dart embeds placeholder OAuth client ID strings when EnvConfig is null.

Firebase authentication
Placeholder API keys and OAuth client IDs

high Verified from source

Integrations fall back to INSERT_YOUR_* strings when env vars are missing.

Application startup Firebase authentication Sugar food scanning
Superwall placement IDs are placeholders

high Verified from source

Many registerPlacement calls still use INSERT_YOUR_* placement id strings.

Main paywall Soft paywalls and quotas Notifications
iOS widget app group ID is a placeholder

medium Verified from source

StreakService uses group.YOUR_BUNDLE_ID.shared for HomeWidget sync.

Sugar streak tracking Home screen widgets

Discoveries

Anonymous auth created from multiple call sites

Verified from source

signInAnonymously appears in onboarding and several repositories, not one gateway.

Guest anonymous access
Manifest deep links without Dart handlers

Verified from source

Some Android/iOS declared URIs are not handled in _processDeepLink.

Deep link handling
No meaningful automated test suite found

Inferred from source

Analysis did not rely on an executable regression suite for app behavior.

Application startup
Feature quotas disabled via local flags

Verified from source

QUOTA_SYSTEM_ENABLED is hard-coded false on major premium feature screens.

Soft paywalls and quotas Learn video lessons Melinda chatbot assistant
Topology test must discover local diagram fixtures

Verified from source

Changes

Clean VibeKB 0.2.0 Stoppr model regeneration

Verified from source

Regenerated the Stoppr living model and /docs as a clean 0.2.0 analysis with canonical important-files schema and current provenance.
Migrate Stoppr to VibeKB 0.2.0 safe repository layout
VibeKB rebootstrap with Explainable Diagrams

Verified from source

Rebuilt .vibekb from Stoppr source using current VibeKB main tooling and static generator.
Upgrade VibeKB runtime and re-analyze Stoppr

Verified from source