diff --git a/MOTORSIGNAL_FREE_PRO_SPEC.md b/MOTORSIGNAL_FREE_PRO_SPEC.md new file mode 100644 index 0000000..9bbc909 --- /dev/null +++ b/MOTORSIGNAL_FREE_PRO_SPEC.md @@ -0,0 +1,342 @@ +# MotorSignal Free / Pro / Lifetime Specification + +**Status:** Planning baseline +**Date:** 2026-09-01 + +## Purpose + +Define the initial product entitlement model for MotorSignal before feature gating and Google Play configuration are finalized. + +This document is a product specification, not a substitute for the billing implementation or Google Play product configuration. + +--- + +# Product Model + +MotorSignal is one application with one account/data model and multiple entitlement levels: + +- `FREE` +- `PRO_MONTHLY` +- `PRO_LIFETIME` + +A user's Firebase account and identity exist independently of whether the user is subscribed. + +Google Play purchase state is the authoritative source for Play entitlement. Local cached state may be used for resilience but must reconcile with authoritative purchase information. + +--- + +# Free + +Free should remain a useful motorcycle telemetry product rather than a crippled trial. + +## Core + +- Motorcycle Garage. +- Basic motorcycle identity. +- Basic ride recording. +- Basic ride history. +- Basic telemetry. +- Basic route view. +- Basic ride statistics. +- User account. +- User profile. +- Friends/social identity. + +## Cloud + +Initial planning assumption: + +- Limited cloud backup. +- Limited cloud history/storage if required by final economics. +- Account-based restore of the included cloud allowance. + +The exact free cloud allowance should be determined after storage/cost modeling. + +--- + +# Pro Monthly + +Pro Monthly unlocks the complete premium MotorSignal experience while the subscription remains active. + +## Cloud + +- Unlimited ride backup. +- Automatic synchronization. +- Motorcycle synchronization. +- Multi-device restore. +- Cloud routes. +- Cloud statistics. +- Cloud reports. + +## Analysis + +- Advanced telemetry analysis. +- Advanced acceleration analysis. +- Advanced braking analysis. +- Advanced lean analysis. +- Advanced graphs. +- Advanced ride comparisons. +- Advanced statistics. + +## Data / Export + +- Unlimited ride history. +- CSV export. +- PDF export. +- Advanced ride reports. + +## Motorcycle Management + +- Multiple motorcycles. +- Expanded motorcycle history. +- Motorcycle-specific statistics. + +## Planning / Social Riding + +- Planned rides. +- Multi-day trip planning. +- Group rides. +- Advanced group-ride functionality. + +## Future Premium Features + +The entitlement system should support adding future premium features without redesigning the subscription architecture. + +Potential examples include camera integration, advanced media synchronization, AI-assisted ride analysis, and additional trip intelligence. + +--- + +# Pro Lifetime + +Pro Lifetime provides the same Pro feature set as Pro Monthly without recurring subscription renewal. + +It should be implemented as a Google Play non-consumable one-time purchase. + +Lifetime access should survive: + +- App restart. +- Logout/login. +- Reinstall. +- Device replacement. +- Restoration on another supported device using the purchasing Google Play account, subject to platform rules. + +--- + +# Feature Capability API + +Do not scatter subscription checks throughout the UI. + +The entitlement layer should expose feature capabilities such as: + +```text +canCloudBackup +canAdvancedTelemetry +canAdvancedAcceleration +canAdvancedBraking +canAdvancedLean +canAdvancedAnalytics +canUnlimitedHistory +canExportCsv +canExportPdf +canUseMultipleMotorcycles +canPlanTrips +canCreateGroupRides +canUseAdvancedGroupRideFeatures +``` + +UI code should ask whether a capability is available rather than directly inspecting product IDs. + +--- + +# Entitlement State + +The entitlement manager should be able to represent at least: + +```text +FREE +PRO_MONTHLY_ACTIVE +PRO_MONTHLY_GRACE +PRO_MONTHLY_ACCOUNT_HOLD +PRO_MONTHLY_EXPIRED +PRO_LIFETIME +UNKNOWN / SYNC_PENDING +``` + +The exact implementation may differ, but the app must distinguish active access from temporary billing/synchronization states. + +--- + +# Subscription Lifecycle + +Must support: + +1. Initial purchase. +2. Purchase acknowledgement. +3. Active subscription. +4. Renewal. +5. Cancellation. +6. Grace period. +7. Account hold. +8. Expiration. +9. Reinstall. +10. Device change. +11. Restore purchases. +12. Temporary network loss. +13. Billing service unavailable. +14. Already-owned product. +15. User cancels the purchase flow. + +--- + +# Paywall Requirements + +The paywall should explain value rather than simply show a locked feature. + +Recommended positioning: + +> **MotorSignal Pro** +> Your rides. Your motorcycle. Your data — everywhere. + +Highlight: + +- Cloud backup. +- Advanced analysis. +- Unlimited ride history. +- Advanced route tools. +- Multiple motorcycles. +- Trip planning. +- Group rides. +- Advanced statistics. + +Offer: + +- Monthly. +- Lifetime. +- Restore Purchases. + +Prices must come from the store's current product details and must not be hard-coded. + +--- + +# Upgrade UX + +When a Free user taps a premium feature: + +1. Explain what the feature does. +2. Clearly identify it as Pro. +3. Show the relevant Pro benefit. +4. Offer upgrade. +5. Allow dismissal without disrupting the rest of the app. + +Do not silently fail or present an unexplained error. + +--- + +# Settings Subscription Area + +The Settings screen should eventually contain: + +```text +MotorSignal Pro + +Plan: Pro Monthly +Status: Active +Next renewal: [store-provided date] + +[Manage Subscription] +[Restore Purchases] +``` + +For Lifetime: + +```text +MotorSignal Pro + +Plan: Pro Lifetime +Status: Active + +Lifetime access +``` + +--- + +# Restore Purchases + +Restore must be a first-class action. + +Test: + +- Reinstall. +- Sign out/sign back in. +- New device. +- Monthly subscription. +- Lifetime purchase. +- Temporary network failure. +- Play Billing service unavailable. + +A user should never need to purchase the same Lifetime entitlement again simply because the application was reinstalled. + +--- + +# Data Ownership + +Subscription status and user data are separate concepts. + +A user who cancels Pro should not automatically lose their MotorSignal account. + +The product must define what happens to data that exceeds the Free allowance after a Pro subscription ends. The preferred approach is to preserve user data while restricting creation/sync of additional premium-only data until the user upgrades again, subject to final storage policy and legal requirements. + +Never silently delete user ride history solely because a subscription expired. + +--- + +# Finalization Checklist + +Before publishing: + +- [ ] Audit every current feature. +- [ ] Assign every feature to Free or Pro. +- [ ] Verify each claimed Pro feature actually works. +- [ ] Implement centralized entitlement checks. +- [ ] Configure Google Play Monthly product. +- [ ] Configure Google Play Lifetime product. +- [ ] Verify current product details are fetched dynamically. +- [ ] Implement purchase flow. +- [ ] Implement restore. +- [ ] Implement subscription management link. +- [ ] Test billing lifecycle. +- [ ] Test reinstall/device restoration. +- [ ] Test offline behavior. +- [ ] Test Firebase/cloud behavior. +- [ ] Verify privacy and Data Safety declarations. +- [ ] Verify Terms and Privacy Policy links. + +--- + +# Planning Matrix + +| Feature | Free | Pro Monthly | Pro Lifetime | +|---|:---:|:---:|:---:| +| Garage | ✓ | ✓ | ✓ | +| Basic ride recording | ✓ | ✓ | ✓ | +| Basic history | ✓ | ✓ | ✓ | +| Basic telemetry | ✓ | ✓ | ✓ | +| Basic route view | ✓ | ✓ | ✓ | +| Account/profile | ✓ | ✓ | ✓ | +| Friends | ✓ | ✓ | ✓ | +| Limited cloud | ✓ | — | — | +| Unlimited cloud | — | ✓ | ✓ | +| Advanced telemetry | — | ✓ | ✓ | +| Advanced acceleration | — | ✓ | ✓ | +| Advanced braking | — | ✓ | ✓ | +| Advanced lean analysis | — | ✓ | ✓ | +| Unlimited history | — | ✓ | ✓ | +| CSV export | — | ✓ | ✓ | +| PDF export | — | ✓ | ✓ | +| Multiple motorcycles | Limited | ✓ | ✓ | +| Trip planning | — | ✓ | ✓ | +| Group rides | — | ✓ | ✓ | +| Advanced statistics | — | ✓ | ✓ | +| Future Pro features | — | ✓ | ✓ | + +**Important:** This matrix must be reviewed against the actual implementation before launch. It should not be treated as permission to advertise unfinished functionality.