Feature Flags Reference¶

Curaway uses Flagsmith for feature flag management. Flags control which features are active in each environment and allow gradual rollouts without code deploys.

Source of truth: config/feature_flags.yaml (58+ flags as of Session 95)

Architecture¶

• Backend: The Python backend queries Flagsmith on startup and caches flag values for 60 seconds (configurable via FLAGSMITH_CACHE_TTL). This prevents excessive API calls and avoids the Flagsmith warning flood issue documented in the troubleshooting runbook.
• Frontend: The React frontend uses the Flagsmith React SDK and evaluates flags client-side based on the current tenant identity.
• Targeting: Flags can be targeted by tenant ID, environment, or percentage rollout.

Flag Inventory¶

Matching¶

Agents¶

Guardrails¶

Performance¶

Conversation Flow¶

OCR¶

Voice¶

Storefront¶

Data¶

Notifications¶

Frontend (Vite Env Vars)¶

These flags live in the frontend repo (curaway-health-navigator) as VITE_* environment variables, not in Flagsmith. They are baked in at build time on Vercel.

Video & Storage¶

LLM Fallback Gateway¶

Chain-of-Thought Prompts¶

Multi-Tenancy Phase 0¶

Multi-Tenancy Phase 1 — Provider Flow¶

Multi-Tenancy Phase 2 — Risk Assessment + MSO¶

Triage + MSO Thresholds (PR #762, Session 95)¶

These flags are stored as Flagsmith per-identity overrides (keyed by tenant ID). They are tunable from the /admin/triage page without a code deploy. See docs/runbook/triage-tuning.md for adjustment guidance.

Multi-Tenancy Phase 3 — Facilitators + Coordinators¶

Patient-facing Transport (#959)¶

Adding New Flags¶

1. Add the flag to config/feature_flags.yaml with a default and description.
2. Create the flag in the Flagsmith dashboard with a descriptive name using snake_case.
3. Set the default value and any tenant-level overrides.
4. In the backend, access the flag via the flagsmith_client:

from app.core.flagsmith import flagsmith_client

if flagsmith_client.get_flag_value("my_new_flag", tenant_id=tenant_id):
    # Feature-flagged code path
    ...

1. In the frontend, use the Flagsmith React hook:

import { useFlags } from 'flagsmith/react';

function MyComponent() {
  const flags = useFlags(['my_new_flag']);

  if (flags.my_new_flag.enabled) {
    return <NewFeature />;
  }

  return <ExistingFeature />;
}

1. Document the flag in this page and update config/feature_flags.yaml.

Flag Lifecycle¶

Flags should not remain in the "Experimental" stage for more than 90 days. If a feature is not promoted to Beta within that window, it should be removed.

Flags Added in Session 40¶

Flags Added in Slice 2a (Admin Users + Tenants)¶

Backs /api/v1/admin/users/* and /api/v1/admin/tenants/*. Both default OFF per the spec rollout: Flagsmith identity-override for SD's Clerk user_id first, then 100%. The router calls is_feature_enabled(flag, tenant_id, identity=actor_user_id) so per-user overrides work.

Identity-override precedence¶

is_feature_enabled(name, tenant_id, *, identity=None) resolves the Flagsmith identifier as identity or tenant_id. For an admin route the caller's Clerk user_id is passed as identity so a single admin can be granted access without flipping the flag for everyone.

Identity override propagation (multi-replica caveat)¶

Identity overrides set via set_identity_override are immediate at the Flagsmith core API (api.flagsmith.com). The Curaway backend runs the Flagsmith SDK in local-evaluation mode with environment_refresh_interval_seconds=60, so the SDK normally takes up to 60 seconds to pick up changes for any given replica's in-memory env document.

To eliminate that lag on the writing replica, every admin write (set_identity_override, env-level update_feature_state, dual-env dual_env_patch, drift resolve_drift, and the matching-engine update_matching_config route that writes matching_weights_v1) calls force_refresh_local_eval_env() after the upstream Flagsmith write succeeds. That helper invokes the SDK's public update_environment() method (flagsmith/flagsmith.py:293-311), which re-GETs the env document and refreshes the local-eval cache in-place. The next is_feature_enabled / get_feature_value call on that replica then resolves the freshly-written value without waiting for the polling cycle. Failures are logged + swallowed so a transient api.flagsmith.com blip never breaks the admin write that just succeeded.

Sibling replicas still wait up to 60s for their own poll cycle (see #1129). For testing-grade "did my override take effect" verification, prefer:

1. Same-replica check via the admin /api/v1/admin/flags/{feature_name}/scope-summary endpoint (sticky-routes to the writing replica when the load balancer honours session affinity).
2. Direct query to api.flagsmith.com/api/v1/environments/{env_key}/identities/?q={identifier} with the admin token (bypasses every SDK cache layer).
3. Wait 60s for sibling replicas to converge.

Future work (#1129 Option D): Redis pub/sub eviction broadcasts env-doc-changed events across replicas for immediate cross-replica consistency. Out of scope today; admin tool runs on a single Railway container so the writing-replica refresh covers the operator UX.

Flags Added in Commerce PR-6 (Webhook Router)¶

Backs the unified canonical webhook ingress at /api/v1/commerce/webhooks/{provider} (spec commerce-module-feature.md §6). Default OFF in both Production and Development; legacy /api/v1/webhooks/{stripe,razorpay} remains authoritative until cutover.

Flags Added in Procedure Onboarding Admin PR-1 (#857)¶

Backs the admin Procedures page + per-facility readiness grid (spec docs/specs/procedure-onboarding-admin-ui.md §9.1). Default OFF in both Production and Development. When the flag is off every /api/v1/admin/procedures/* route returns 503 with error_code PROCEDURE_ADMIN_DISABLED_001 so the admin SPA can grey-out the menu entry. Per Curaway dual-env flag policy flip in BOTH envs together.