User Story: Subscription Management & RevenueCat Pro Features

Catálogo histórico

Este documento no forma parte del modo operativo. El filtro del menú lo oculta por defecto.

Estado de fase (MASTER-00): MVP — alcance del MVP Shipaton sujeto a resultados de Gate 0 y PoC. Gobernanza: MASTER-00.

User Story: Subscription Management & RevenueCat Pro Features

---

User Story Statement

As a free tier user or software engineering manager,
I want to subscribe to DocuGraph Pro via an in-app paywall (or web portal) powered by RevenueCat, restore existing purchases across my devices, and seamlessly unlock Pro capabilities (unlimited projects, deep MCP context extraction, automated audit suite, and PostgreSQL cloud sync),
So that my entire team can scale our atomic documentation workflows without feature or context depth restrictions.

---

Business Rationale & User Impact

Monetization powers the long-term sustainability of DocuGraph as detailed in the freemium business model in VISION-00. Leveraging RevenueCat simplifies multiplatform subscription handling across Google Play, Apple App Store, and Web payments. Seamless paywall triggers, instant entitlement activation (pro_tier), and offline JWT claim caching ensure a smooth user experience while protecting Pro feature gates.

---

User Flow & Interaction Overview

1. User attempts a gated Pro action (e.g., creating a 4th project US-02, requesting MCP context with maxDepth > 2 US-04, or setting up PostgreSQL cloud sync).
2. Application displays the PaywallModal (FE-05), presenting monthly ($19/month) and annual ($190/year) subscription plans.
3. User selects a plan and completes purchase via StoreKit / Google Play Billing on mobile, or Web checkout (RevenueCat Web Billing) on Desktop.
4. RevenueCat processes transaction, validates receipt, and grants entitlement pro_tier.
5. Backend (BE-06) issues an updated JWT access token containing claim entitlement: "pro_tier", cached locally for offline verification.
6. PaywallModal dismisses, displaying a success toast, and instantly unlocks the requested Pro feature.

---

Acceptance Criteria (Gherkin Format)

Scenario 1: In-App Purchase Paywall Triggering

Given a Free tier user attempting to perform a gated Pro action (such as creating a 4th project or requesting deep MCP context)
When the user clicks the gated action
Then the application intercepts the request and opens the PaywallModal component (FE-05)
And displays active RevenueCat offerings including Monthly ($19/mo) and Annual ($190/yr) pricing tiers
And lists Pro feature benefits (unlimited projects, deep MCP extraction, cloud sync)

Scenario 2: Purchase Completion & Pro Entitlement Unlocking

Given the PaywallModal is displayed to the user
When the user selects the Annual plan and completes the purchase process successfully
Then RevenueCat SDK validates the transaction receipt and grants entitlement ID "pro_tier"
And the client dispatches an entitlement sync request to the backend (operationId: checkEntitlement)
And the backend updates the database record (table: subscriptions) with active status
And the UI dismisses the paywall and immediately unlocks all Pro feature capabilities

Scenario 3: Entitlement Verification & JWT Offline Caching

Given a Pro user operating the application in an offline environment without active internet connectivity
When the client checks user permissions for Pro feature execution
Then the application verifies the cached local JWT token claim `entitlement: "pro_tier"`
And permits execution of Pro features if the cached token timestamp is within the 7-day offline grace period

Scenario 4: Restore In-App Purchases Across Devices

Given an active Pro subscriber installing DocuGraph on a new secondary device
When the user opens the PaywallModal (FE-05) and clicks the "Restore Purchases" button
Then RevenueCat SDK queries the app store backend for existing valid receipts tied to the user account
And upon finding an active subscription, syncs entitlement state and grants "pro_tier" access on the new device without requiring double payment

---

Functional Requirements & Constraints

1. Entitlement Identifier: The single source of truth for the RevenueCat Pro entitlement is pro_tier.
2. Desktop & Web Fallback: On Desktop JVM targets where native mobile store kits are unavailable, purchases are routed to RevenueCat REST API v1 (GET /v1/subscribers/{app_user_id}) via Stripe/RevenueCat Web Checkout.
3. Offline Grace Period: JWT entitlement claims are cached with AES-256 encryption and validated offline for up to 7 consecutive days.

---

Downstream Atomic Mapping

This User Story serves as the direct upstream source of truth for the following downstream specifications:

• Backend Specification: BE-06_paywall-check-entitlement.md (BE-06) — Ktor route handler for GET /api/v1/subscriptions/entitlement.
• API Contract: openapi.yaml — Single source of truth for REST endpoint with operationId: checkEntitlement.
• Frontend Specification: FE-05_paywall-modal.md (FE-05) — Compose Multiplatform Paywall modal component.
• Database Schema: 01_DATABASE_SCHEMA.md (table: subscriptions) — Relational user subscriptions entity table.

---

Traceability Index

• Upstream Dependencies:
  • docs/00_BUSINESS_VISION.md (VISION-00) — Strategic Freemium Business Model.
  • US-01_login.md (US-01) — Authenticated User Session requirement.
• Downstream Direct Linkages (Planned M2/M3):
  • BE-06_paywall-check-entitlement.md (BE-06)
  • FE-05_paywall-modal.md (FE-05)
• Related Stories:
  • US-02_create_project.md (US-02) — Project count limit gating.
  • US-04_get_task_context.md (US-04) — Context depth limit gating.