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.

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¶

agent_enhanced_matching¶

Controls whether the AI agent uses the enhanced multi-signal matching pipeline that combines Qdrant semantic search, Neo4j graph traversal, and LLM re-ranking.

agent_explanations_enabled¶

Controls whether the AI agent generates natural-language explanations for why each provider was recommended.

guardrail_input_classifier_enabled¶

Controls whether inbound user messages are classified by the guardrail system before reaching the LLM.

guardrail_output_validator_enabled¶

Controls whether LLM responses are scanned against forbidden output patterns before being sent to the user.

guardrail_file_validation_enabled¶

Controls whether uploaded files are validated against the size, type, and content rules defined in config/guardrails.yaml.

DOCTORS_IN_MATCHING¶

Controls whether the matching pipeline considers individual doctors in addition to provider-level matches. When enabled, the system returns both the matched provider and the specific doctor(s) at that provider who are most relevant.

PUBLIC_API_ENABLED¶

Controls the entire /api/v1/public/ router. When disabled, all public storefront endpoints return 503 Service Unavailable.

STOREFRONT_PAGES_ENABLED¶

Controls frontend storefront routes. When disabled, storefront URLs redirect to the homepage.

PUBLIC_SEARCH_ENABLED¶

Controls the unified search endpoint independently from the rest of the public API.

STOREFRONT_CACHE_ENABLED¶

Controls whether storefront responses are cached. When disabled, all requests hit the database directly (useful for debugging).

PROVIDER_COMPLETENESS_DISPLAY¶

Controls whether completeness badges are shown on provider listing cards in the storefront.

embedding_document_matching¶

Controls whether uploaded patient documents (medical reports, imaging) are embedded and used as additional signals in provider matching.

Adding New Flags¶

1. Create the flag in the Flagsmith dashboard with a descriptive name using snake_case.
2. Set the default value and any tenant-level overrides.
3. 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 following the format above.

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.