Core Concepts

Understanding Hoist's data model and terminology.

Hierarchy

Organization
└── Project
    └── Environment
        └── Flag Configuration
            └── Targeting Rules

Organizations

Organizations are the top-level tenant in Hoist. They provide:

• Multi-tenancy - Complete isolation between organizations
• Billing boundaries - Usage is tracked per organization
• Team management - Members belong to organizations with roles

Roles

Role	Permissions
Owner	Full access, can delete organization
Admin	Manage projects, flags, and members
Member	Create and manage flags
Viewer	Read-only access

Projects

Projects group related feature flags together. Common patterns:

• By application: web-app, mobile-app, api
• By team: payments, onboarding, search
• By product: enterprise, consumer

Each project has:

• Unique key within the organization
• Set of environments
• Project-specific API keys

Environments

Environments represent deployment stages. Flags can have different configurations per environment.

Default Environments

Projects typically start with:

• Development - Local development, liberal settings
• Staging - Pre-production testing
• Production - Live users, conservative changes

Environment-Specific Configuration

Each flag can have different:

• Default value
• Targeting rules
• Enabled/disabled state
• Rollout percentages

Feature Flags

Feature flags control application behavior without code deploys.

Flag Types

Type	Use Case	Example
Boolean	On/off switches	enable-dark-mode
String	Configuration values	checkout-version: "v2"
Number	Numeric settings	request-timeout: 30
JSON	Complex configuration	feature-limits: {"maxItems": 100}

Flag Key

The unique identifier used in code:

• Lowercase with hyphens: new-checkout-flow
• Descriptive and stable
• Cannot be changed after creation

Flag Lifecycle

1. Active - Flag is evaluating normally
2. Deprecated - Marked for removal (warnings in dashboard)
3. Archived - Soft-deleted, no longer evaluates

Targeting

Targeting determines which users receive which flag values.

Targeting Key

The unique identifier for the user being evaluated:

hoist.Context{
    TargetingKey: "user-123",  // Required for targeting
}

Attributes

Additional context for targeting rules:

hoist.Context{
    TargetingKey: "user-123",
    Attributes: map[string]any{
        "email":    "user@example.com",
        "plan":     "enterprise",
        "country":  "US",
        "beta":     true,
    },
}

Targeting Rules

Rules evaluate in order until one matches:

1. Identity Overrides - Specific targeting keys always get a value
2. Segment Rules - Target users in defined segments
3. Attribute Rules - Match on attribute conditions
4. Rollout Rules - Percentage-based rollouts
5. Default Value - When no rules match

Operators

Operator	Description	Example
equals	Exact match	plan equals "pro"
not_equals	Not equal	country not_equals "EU"
contains	String contains	email contains "@company.com"
starts_with	String prefix	email starts_with "admin"
ends_with	String suffix	email ends_with ".gov"
in	In list	plan in ["pro", "enterprise"]
not_in	Not in list	country not_in ["CN", "RU"]
greater_than	Numeric comparison	age greater_than 18
less_than	Numeric comparison	items less_than 100

Segments

Segments are reusable groups of users.

Static Segments

Explicit list of targeting keys:

Segment: beta-testers
Members: ["user-1", "user-2", "user-3"]

Rule-Based Segments

Dynamic membership based on attributes:

Segment: enterprise-users
Rules:
  - plan equals "enterprise"
  - OR company_size greater_than 100

Using Segments in Rules

If user in segment "beta-testers"
  Return: true

API Keys

API keys authenticate SDK requests.

Server Keys

Format: hoist_live_* or hoist_test_*

• Full access to flag configuration
• Local evaluation with streaming updates
• Used in backend services

client, _ := hoist.NewClient(hoist.Config{
    APIKey: "hoist_live_xxx",  // Server key
})

Client Keys

Format: hoist_pk_*

• Server-side evaluation only
• Protects targeting rules from exposure
• Used in browser/mobile apps

Test vs Live Keys

• Test keys (hoist_test_*): Non-production environments
• Live keys (hoist_live_*): Production environment

Real-Time Updates

Flag changes propagate instantly to connected SDKs.

Update Flow

Dashboard change
       ↓
Database write
       ↓
PostgreSQL NOTIFY
       ↓
Redis pub/sub
       ↓
WebSocket hub
       ↓
Connected SDKs
       ↓
Local cache refresh

Streaming vs Polling

Mode	Latency	Use Case
Streaming	Real-time (~100ms)	Default for server keys
Polling	Configurable interval	Firewalled environments

Evaluation Reasons

Each evaluation includes a reason explaining the result:

Reason	Description
DEFAULT	No rules matched, using default value
TARGETING_MATCH	Matched a targeting rule
SEGMENT_MATCH	Matched via segment membership
ROLLOUT	Percentage rollout bucket
IDENTITY_OVERRIDE	Specific user override
DISABLED	Flag is disabled
NOT_FOUND	Flag doesn't exist
ERROR	Evaluation error occurred

Next Steps

• Go SDK - Implementing flag evaluation
• TypeScript SDK - Browser and Node.js usage
• API Authentication - Understanding auth methods