Skip to main content

Source: ocean/docs/adr/0019-feature-flag-gating-by-plan.md | ✏️ Edit on GitHub

ADR-0019: Feature Flag Gating by Plan (PostHog)

Date: 2025-08-13

Status​

Accepted

Context​

We need plan-based feature control to enable Free → Pro/Team upsell and progressive rollout, without hardcoding plan checks everywhere.

Decision​

  • Use PostHog feature flags as the primary gating mechanism for plan-based features.
  • Client: usePostHogFeature and useFeatureFlag helpers control UI visibility and UX.
  • Server: Enforce critical plan constraints in resolvers where applicable (authorization checks still required), but prefer feature flags for UX gating.
  • Standardize flag keys in src/hooks/use-posthog-features.ts (e.g., TEAM_INVITES_ENABLED, API_ACCESS_ENABLED, ADVANCED_ANALYTICS).

Implementation Details​

  • Identify users and group by organization in PostHog
  • Set person/group properties: plan, subscription_status for targeting
  • Use environment presets for default flag rollout per plan
  • Client usage:
    • Billing page already uses embed-payments and advanced-billing flags to reveal sections
    • Future: gate team invites UI, analytics pages, API settings, export tools

Consequences​

Positive​

  • Centralized, dynamic control of features per plan without redeploys
  • Safe rollouts and A/B tests

Negative​

  • Requires discipline to avoid relying solely on client flags for security; server must still enforce permissions

Alternatives Considered​

  1. Hardcoded plan checks everywhere
  • Rejected: rigid, redeploys required, poor experimentation
  1. Separate in-DB feature toggles
  • Rejected: duplicates PostHog, more custom code to maintain

References​

  • ADR-0012: GraphQL-Based Billing Architecture
  • src/hooks/use-posthog-features.ts