Technical reference. For task-based help, see the corresponding user guide.

Documentation status: reviewed against implementation · Reviewed: 2026-07-21 · Primary users: eligible family users and actively subscribed coaches · Surfaces: mobile web, native wrapper and platform API

The app asks for a store review only after sustained use, and never through a blocking custom rating form. Family and coach eligibility are tracked independently so a dual-role account's activity in one product context cannot consume the other context's prompt.

trialing, canceled, expired or missing coach subscriptions do not qualify. Recording a coach day is idempotent for that local calendar date and returns subscriptionEligible: false without advancing state when the exact active-subscription rule is not met.

1. After a family actor successfully creates an activity for their own household, the platform adds that local day key if it is new.
2. Coach-created activity in a client context does not count toward the family's review eligibility.
3. On the seventh distinct day, firstEligibleAt is retained in family reviewPrompt state.

1. On an eligible coach dashboard route, mobile calls POST /coach/review-prompt/activity-day.
2. The platform selects the coach's primary active organization and latest coach subscription. Only status active records the day.
3. Coach state is stored separately as coachReviewPrompt; repeated visits on the same day do not increase the count.

1. The host waits two seconds after reaching the eligible home route.
2. It loads/records the audience state, checks seven days, selected baby or active subscription, cooldown, native platform and prompt contention.
3. If eligible, it claims the shared reviewPrompt experience and calls native storeReview.request.
4. There is no app-rendered star dialog. iOS/Android decides whether and how to show its store sheet.

1. Only when the bridge returns true does mobile report review_prompt_shown and PATCH the attempt with platform and current web-release version.
2. The server sets lastRequestedAt, lastRequestedPlatform, lastRequestedAppVersion and nextAllowedAt six months later.
3. Unsupported bridge, native denial, exception or a lost prompt-experience race does not consume the server cooldown.

• The feature renders no persistent settings panel and never blocks dashboard use.
• A notification banner has the same shared presentation channel; the review attempt waits/abandons rather than overlapping it.
• Eligibility/API/native errors are swallowed as best-effort failures. A later eligible visit can retry.
• A successful native request does not prove that the operating system displayed a sheet or that the user left a review.
• The manual Review app side-menu link is a separate direct store action and is not governed by these automatic eligibility rules.

• State is bound to the authenticated actor; no request accepts another user ID.
• Coach attempt writes recheck day count, cooldown and the latest primary-organization subscription inside the write.
• The current family attempt write checks the family actor and request shape/date but does not independently re-evaluate seven days, selected baby or cooldown. Those family gates currently live in the mobile host.
• Family and coach JSON state use different user fields. Default role/route chooses which state a dual-role actor evaluates.
• Client timing and the prompt-experience lock improve presentation but do not replace server attempt validation.

“Request accepted” is the strongest product signal available. Store APIs intentionally do not disclose whether the sheet appeared or whether a review was submitted. Also note the current integrity asymmetry: coach attempt eligibility is server-enforced, while family attempt eligibility is client-enforced before a role-checked write.

1. [ ] Seven distinct dates are required; multiple events/visits on one date count once.
2. [ ] Mobile family eligibility requires selected baby and self-created family activity days; tests also capture that the current family attempt endpoint does not recheck those gates.
3. [ ] Coach requires latest subscription status exactly active both when counting and recording attempt.
4. [ ] Family and coach states remain separate for a dual-role actor.
5. [ ] Prompt runs only on native iOS/Android home routes after the delay.
6. [ ] Notification banner and review request never display concurrently.
7. [ ] Cooldown is written only after native returns true and lasts six calendar months.
8. [ ] Unsupported/failing native API does not block the app or consume cooldown.

• Mobile web: mobile-web/src/components/ReviewPromptHost.tsx, mobile-web/src/utils/review-prompt.ts, mobile-web/src/webview/native-messages.ts
• Platform: platform/packages/shared/src/review-prompt.ts, platform/apps/api/src/routes/family-routes.ts, platform/apps/api/src/routes/coach-routes.ts, platform/apps/api/src/services/coach-review-prompt-service.ts, family activity/review state services
• Native wrapper: store-review bridge handler and platform store-review adapter under mobile-wrapper/src/native/

• 07 — Activity tracking
• 15 — Coach dashboard and practice analytics
• 27 — Announcements and notification banners
• 32 — Realtime updates and push notifications