Skip to main content

Onboarding and Setup Feature Context

Source: .agents/references/features/onboarding-and-setup.md

Content​

Onboarding and Setup Feature Context

Purpose​

Onboarding and setup cover new creator/community setup, onboarding prompts, get-started flows, community signup, plan selection, business setup overlays, media uploads, referral codes, base currency, and social/profile setup. This domain helps users create or configure a community and reach the next actionable product step.

User-Facing Workflows​

  • Users visit src/pages/get-started/ to initialize or update onboarding information.
  • Onboarding overlays prompt for community setup, benefits, media upload, plan selection, and next-step loading states.
  • Creator setup may include base currency, social media, referral code, community data, and plan selection.
  • Signup flows may be embedded in community/product experiences and must not break public-page CTAs.
  • Loading, nudges, and background animation should feel lightweight and avoid excessive state syncing.
  • New onboarding/paywall plan selection sunsets Basic from the visible creator choice: use the PlanSelectionOverlay-specific Pro/Platinum visible plan list for cards, benefit modals, and compare-plan modals. All shared plan comparison modals hide Basic and compare only Pro/Platinum; Basic can still appear in non-comparison subscription, billing, and benefit-modal surfaces.
  • /subscribe-plan selection controls hide Basic unless the current selected plan is Basic. Existing Basic users can still keep/select Basic, while non-Basic selection flows only offer Pro and Platinum.
  • Exact /get-started is indexable and a read-only agent recommendation target. Exact /subscribe-plan remains noindex but is a read-only agent recommendation target. Nested route variants and private account, subscription, payment, or checkout state are not public agent context.
  • /portal/plan-billing change-plan controls use the same Basic exception: hide Basic for non-Basic current plans, but keep Basic selectable for current Basic users.

Key Entrypoints​

  • Routes:
    • src/pages/get-started/index.page.tsx
    • src/pages/get-started/components/
    • src/pages/get-started/hooks/
    • src/pages/choose-a-plan/
    • src/pages/subscribe-plan/
    • src/pages/referral/
  • Features:
    • src/features/CmOnboarding/
    • src/features/CommunityOnboardingSuccessScreen/
    • src/features/CommunitySignupModal/
    • src/features/BusinessSetupOverlay/
    • src/features/OnboardingBackground/
    • src/features/OnboardingBenefitOverlay/
    • src/features/OnboardingMediaUploadOverlay/
    • src/features/OnboardingPromptLoadingOverlay/
    • src/features/OnboardingPromptOverlay/
    • src/features/PlanSelectionOverlay/
    • src/features/SignUpPopup/
  • Hooks:
    • src/pages/get-started/hooks/useInitialBaseCurrency.ts
    • src/pages/get-started/hooks/useOnboardingCommunity.ts
    • src/pages/get-started/hooks/useUpdateSocialMedia.ts
    • src/hooks/useOnboardingReferralCode.js
    • src/hooks/useInitCommunitySignup.js
    • src/hooks/useSelectAudience.ts
    • src/hooks/useNasPlan.ts
  • Services:
    • src/services/nasPlan/nasPlanService.js
    • src/services/userService.js
    • src/services/communitiesService.js
    • src/services/referral/referralService.ts
  • Utilities:
    • src/utility/onboardingFunnelAnalyticsConsts.ts
    • src/utility/platformPlanConstants.ts
    • src/utility/communityHelpers.js

Data Flow and Service Boundaries​

  • Onboarding flows often combine authenticated user state, community state, plan state, and route params. Inspect the parent route or overlay wrapper before adding local state.
  • Plan selection and subscription may share data with checkout/payment surfaces. Load checkout-and-payments.md when touching purchase or subscription steps.
  • Plan comparison and benefit modal components are shared with /subscribe-plan. Basic is sunset from all plan comparison modals, but can still appear in non-comparison plan cards, benefit modals, subscription, and billing surfaces unless those flows explicitly pass a filtered plan list.
  • Base currency and social media updates are service-backed. Use the service { data, error } pattern and preserve existing error toast behavior.
  • Referral code handling may use storage or query params. Use existing hooks/utilities rather than direct browser storage access.
  • Analytics constants exist for onboarding funnels. Prefer existing event names and IDs.

Conventions and Gotchas​

  • Do not mirror props into local state for onboarding displays; derive current step/progress from existing state when possible.
  • Do not remove Basic globally while sunsetting it from onboarding and comparison modals. Basic can still appear in non-comparison subscribe/billing contexts unless those flows opt into a Pro/Platinum plan list.
  • Avoid useEffect for user-event actions such as submit, save, or continue. Put event-specific logic in handlers.
  • Keep overlays and modals focused. If reusable UI grows beyond a tiny helper, move it into a named component file.
  • Use direct t() calls for visible copy; keep keys meaningful and sentence-shaped.
  • Use Tailwind utilities, not inline styles, for backgrounds/layout unless animation APIs require dynamic values.
  • Guard missing user/community/plan data explicitly because onboarding can start from multiple entrypoints.
  • .agents/rules/clean-react.mdc
  • .agents/rules/no-unnecessary-usecallback.mdc
  • .agents/rules/no-functions-in-effect-deps.mdc
  • .agents/rules/no-try-catch-service-api.mdc
  • .agents/rules/web-security.mdc
  • .agents/references/coding-standard/useeffect-guidance.md
  • .agents/references/features/checkout-and-payments.md for paid plan/subscription steps

Useful Graph Queries and Fallback Searches​

Use the terms below with search_graph/search_code, then run trace_path on central onboarding symbols. Run these shell searches only as documented fallbacks.

rtk rg "onboarding|GetStarted|baseCurrency|PlanSelection|CommunitySignup|referral" src/pages/get-started src/features src/hooks src/services src/utility
rtk rg "Onboarding" src/features
rtk rg "onboardingFunnel|useNasPlan|useOnboardingCommunity" src

Update Triggers​

Update this reference when onboarding steps, plan selection, signup modal behavior, referral handling, or creator setup service contracts change.