Skip to main content

MVP Feature Flags

This document describes the PostHog feature flag system that gates non-MVP admin surfaces for the Legacy Launch.

Overview​

All flags default to OFF in PostHog. This ensures a clean, focused admin experience for MVP launch. Non-MVP features remain hidden unless explicitly enabled in the PostHog dashboard.

Feature Flag Registry​

Flags are defined in apps/web/src/lib/features.ts:

Flag KeyPurposeSurfaces Gated
studioPrint studio access/admin/print-studio, Print studio sidebar item
label_portalLabel portal access/label/*, Labels desk in admin
demo_portalsDesigner demos/demo/*
new_checkoutFuture checkout flow(future)
admin_white_gloveWhite glove managed services/admin/white-glove desk
admin_card_generationCard generation pipeline/admin/card-generation desk
admin_stageEntire Slapp Stage section (Phase 2)All /admin/stage/* routes and sidebar section
admin_labsNon-MVP admin desksCampaigns, site content, gift cards, inventory, shipping, redemptions (ComingSoon), finance revenue/refunds placeholders, feature-flags desk, integrations, ops tools, audit log

MVP Admin Navigation Allowlist​

When flags are OFF (default), only these sidebar items appear:

Command​

  • Command center (/admin)
  • Alerts (/admin/notifications)

Fulfillment (MVP items only)​

  • Fulfillment overview
  • Orders
  • Batches and codes
  • Slap codes
  • Mint batch

Catalog (MVP items only)​

  • Catalog overview
  • Pack SKUs
  • Legacy (slugs + audio)

Artists​

  • All artists

Analytics​

  • Overview (/admin/analytics)
  • Engagement
  • Conversion
  • Artists (leaderboard)
  • Revenue

Marketing & Sales (MVP items only)​

  • Lead pipeline

Customer Care​

  • Support tickets
  • Mailing list

Finance​

  • Commissions (real MVP desk)

Growth & Risk​

  • Affiliates
  • Abuse radar

Users & Access​

  • Staff accounts
  • Artist accounts

Site Admin​

  • Business settings
  • Env / setup

Hidden by Default (ComingSoon Scaffolds + Phase 2)​

These items do NOT appear in the sidebar when flags are off:

  • Print studio — requires studio flag
  • Card generation — requires admin_card_generation flag
  • White glove — requires admin_white_glove flag
  • Labels desk — requires label_portal flag
  • Campaigns — requires admin_labs flag
  • Site content — requires admin_labs flag
  • Gift cards — requires admin_labs flag
  • Card designs/templates — requires admin_labs flag
  • Inventory — requires admin_labs flag
  • Shipping — requires admin_labs flag
  • Redemptions (ComingSoon) — requires admin_labs flag
  • Revenue overview — requires admin_labs flag
  • Refunds & disputes — requires admin_labs flag
  • Feature flags desk — requires admin_labs flag
  • Integrations — requires admin_labs flag
  • Ops tools — requires admin_labs flag
  • Audit log — requires admin_labs flag
  • Entire "Slapp Stage · Phase 2" section — requires admin_stage flag

Implementation​

apps/web/src/lib/dashboardNav.ts contains:

  1. MVP_ALLOWLIST — Set of nav item IDs that always appear when flags are off
  2. FEATURE_FLAG_GATES — Map of item IDs to required flag keys
  3. shouldShowNavItem() — Filter function applied to all nav items
  4. adminNavSections() — Accepts enabledFeatureFlags array and filters sections/items

Feature Flag Hook​

apps/web/src/hooks/useFeatureFlag.ts provides:

  • useFeatureFlag(flag) — Returns boolean for single flag
  • useFeatureFlags(flags) — Returns map of flag states
  • Fail-closed behavior — Returns false when PostHog unavailable or flag not found

Route Protection​

apps/web/src/components/FeatureGate.tsx provides:

  • FeatureGate — Wraps content with flag check, shows fallback when disabled
  • FeatureGateInline — Simple inline gate with no fallback UI

AdminPortal Integration​

apps/web/src/views/portals/AdminPortal.tsx:

  1. Calls useFeatureFlags() for all admin flags
  2. Maps enabled flags to PostHog flag keys
  3. Passes enabledFeatureFlags to adminNavSections()
  4. Wraps non-MVP desks with <FeatureGate> components

Enabling Flags in PostHog​

For Staging QA​

  1. Open PostHog dashboard for staging environment
  2. Navigate to Feature Flags
  3. Create or enable the flag (e.g., admin_labs, admin_stage)
  4. Set rollout to 100% for staging
  5. Refresh admin portal — gated items now appear

For Production​

Only enable flags after thorough testing in staging:

  1. Open PostHog dashboard for production
  2. Enable flag with appropriate rollout percentage
  3. Monitor for issues
  4. Gradually increase rollout if stable

Testing​

Verify Navigation Filtering​

  1. With all flags OFF (default):

    • Sidebar should show only MVP allowlist items
    • ComingSoon scaffolds and Phase 2 items should be hidden
    • Direct URL access to gated routes shows "not enabled" page

  2. Enable admin_labs flag:

    • Campaigns, site content, etc. should appear in sidebar
    • Direct access to those routes works

  3. Enable admin_stage flag:

    • "Slapp Stage · Phase 2" section appears in sidebar
    • Stage routes accessible

Verify Route Guards​

  1. Disable all flags in PostHog
  2. Attempt direct navigation to /admin/card-generation
  3. Should show FeatureGate fallback with instructions
  4. Enable admin_card_generation flag
  5. Refresh — desk should now load

Code Locations​

  • Flag registry: apps/web/src/lib/features.ts
  • Hook: apps/web/src/hooks/useFeatureFlag.ts
  • Gate component: apps/web/src/components/FeatureGate.tsx
  • Navigation filter: apps/web/src/lib/dashboardNav.ts
  • AdminPortal integration: apps/web/src/views/portals/AdminPortal.tsx

Notes for Agents​

  • Never change flag defaults to true in code — flags default OFF by design
  • PostHog enablement is environment-specific — staging and prod are independent
  • MVP allowlist is authoritative — do not add ComingSoon items to allowlist
  • Prefer allowlist over individual flags — use admin_labs catch-all for misc Phase 2 desks
  • Test with flags OFF first — that's the default prod state for MVP launch