Getting started¶

This section explains the core concepts of the FeatureFlags system and how they work together.

Flags¶

A flag is a boolean feature toggle that can be either true or false. Flags are used to enable or disable features in your application.

Flags are defined with:

Name: A unique identifier for the flag (e.g., NEW_UI_FEATURE, BETA_MODE)
Default value: The fallback value when conditions are not met
Conditions: Rules that determine when the flag should be enabled
Enabled state: Whether the flag is active in the system

Example flag usage:

from featureflags_client.http.client import FeatureFlagsClient
from featureflags_client.http.managers.requests import RequestsManager

# Define your flags with default values
class Flags:
    NEW_UI_FEATURE = False
    BETA_MODE = False
    PREMIUM_FEATURES = False

# Initialize client
manager = RequestsManager(
    url="http://localhost:8080",
    project="my-project",
    variables=[],
    defaults=Flags,
    request_timeout=5,
    refresh_interval=10,
)
client = FeatureFlagsClient(manager)

# Preload flags and values from server
client.preload()

# Use flags in your application
with client.flags({"user.id": "123"}) as flags:
    if flags.NEW_UI_FEATURE:
        show_new_ui()
    else:
        show_old_ui()

Values¶

A value is a configurable parameter that can be of different types (string, integer, etc.). Values are used for A/B testing, dynamic configuration, and feature customization.

Values can be:

Strings: Text values like configuration settings
Integers: Numeric values like pagination limits, prices, or timeouts
Timestamps: Date/time values
Sets: Collections of values

Example value usage:

# Define your values with default values
class Values:
    PAGINATION_LIMIT = 10
    PRODUCT_PRICE = 99.99
    FEATURE_MESSAGE = "Welcome to our new feature!"

# Initialize client
manager = RequestsManager(
    url="http://localhost:8080",
    project="my-project",
    variables=[],
    values_defaults=Values,
    request_timeout=5,
    refresh_interval=10,
)
client = FeatureFlagsClient(manager)

# Preload values from server
client.preload()

# Use values in your application
with client.values({"user.id": "123"}) as values:
    items_per_page = values.PAGINATION_LIMIT
    price = values.PRODUCT_PRICE
    message = values.FEATURE_MESSAGE

Common use cases for values:

A/B Testing: Different prices, messages, or configurations
Dynamic Configuration: Pagination limits, timeouts, feature limits
Personalization: User-specific content or settings
Feature Customization: Different behavior based on user segments

Evaluation¶

The FeatureFlags system uses a client-side evaluation architecture to minimize server requests and provide fast, responsive feature flag checking.

How it works:

Server Storage: All flags, values, and their conditions are stored in the server database
Client Synchronization: The client periodically syncs with the server to download: - Flag definitions and their conditions - Value definitions and their conditions - Variable definitions - All evaluation rules and logic
Client-Side Evaluation: When checking a flag or value, the client evaluates the conditions locally using the synced data
Context-Based: Evaluation uses the provided context (user attributes, request data, etc.)

Benefits:

Low Latency: No network requests during flag evaluation
High Performance: Fast feature flag checks
Reduced Server Load: Minimal RPS to the server
Offline Capability: Works even when server is temporarily unavailable

Synchronization:

Clients sync with the server at regular intervals (configurable)
Changes to flags/values are propagated to clients within the sync interval
Clients can preload data on startup for immediate availability

Variables¶

Variables are the building blocks of conditions. They represent attributes or context that can be used to make decisions about flags and values.

Variables have:

Name: Identifier like user.id, user.email, request.ip
Type: STRING, NUMBER, TIMESTAMP, or SET
Value: The actual data from your application context

These are the examples of variables that you may need to define in your project (featureflags client does not define any variables for you):

User Variables:

user.id: Unique user identifier
user.email: User’s email address
user.role: User’s role (admin, premium, etc.)
user.country: User’s location

Request Variables:

request.ip: Client’s IP address
request.user_agent: Browser/device information
request.path: Current URL path
request.method: HTTP method

On first application start, when client syncs with the server, client sends all variables to the server and only then new variables can be used in flags UI.

Example variable usage:

from featureflags_client.http.types import Variable, VariableType

# Define variables for your project
USER_ID = Variable("user.id", VariableType.NUMBER)
USER_EMAIL = Variable("user.email", VariableType.STRING)
REQUEST_IP = Variable("request.ip", VariableType.STRING)

# Use variables in conditions
manager = RequestsManager(
    url="http://localhost:8080",
    project="my-project",
    variables=[USER_ID, USER_EMAIL, USER_ROLE, REQUEST_IP],
    defaults=Flags,
    request_timeout=5,
    refresh_interval=10,
)

The system evaluates these conditions using the context you provide when checking flags and values.