Feature Flag

Two systems, two purposes

Gram has two distinct feature-gating mechanisms. They are not interchangeable — pick based on the semantics of the flag, not on convenience.

Decision rule

Use productfeatures when the toggle represents a durable, org-level capability that admins control or that maps to what the customer purchased (entitlement). Think: GCP's per-project API enablement.

Use PostHog flags when you're rolling something out gradually, dogfooding a change internally, or need per-user granularity. The flag is expected to disappear once the feature ships to everyone.

productfeatures

Concepts

• Feature constants live in server/internal/productfeatures/features.go as typed string constants (Feature type).
• State is stored in organization_features (PostgreSQL). Soft-deletes track removal.
• productfeatures.Client checks Redis first (15 min TTL), falls back to Postgres, and returns errors on lookup failures — use PlatformFeatureCheck when you want silent false-on-error degradation.
• The management API (/rpc/productFeatures.get and /rpc/productFeatures.set) exposes the state to the dashboard and Speakeasy ops.

Adding a new product feature

1. Declare the constant in server/internal/productfeatures/features.go:

const (
    FeatureMyNewFeature Feature = "my_new_feature"
)

2. Add it to the Goa design in server/design/shared/productfeatures.go:

// In the setProductFeature method's Enum constraint:
Enum("logs", "tool_io_logs", ..., "my_new_feature")

// In the getProductFeatures Result:
Attribute("my_new_feature_enabled", Boolean, "Whether my new feature is enabled")

3. Wire the result in server/internal/productfeatures/snapshot.go:

MyNewFeatureEnabled: isEnabled(FeatureMyNewFeature),

4. Regenerate with mise run gen:goa-server (Goa codegen updates gen/).

Checking a feature at runtime (Go)

// inject *productfeatures.Client — it's already wired in cmd/gram/start.go
enabled, err := pf.IsFeatureEnabled(ctx, organizationID, productfeatures.FeatureMyNewFeature)
if err != nil {
    return fmt.Errorf("check my_new_feature: %w", err)
}

Use PlatformFeatureCheck (returns bool, logs errors, degrades to false) only in non-critical paths where you want silent degradation.

Checking in the React dashboard

const { data: features } = useProductFeatures();
if (features?.myNewFeatureEnabled) { ... }

PostHog feature flags

Concepts

• Flag keys are typed Flag constants in server/internal/feature/flags.go. The constant's comment is the one place per flag that records where it is evaluated (server, dashboard, or both) and how it is targeted.
• The server reaches PostHog only through feature.Provider (inject it; tests use feature.InMemory). The dashboard uses useFeatureFlag().
• For org-scoped server gates, distinctID is the organization ID and groups is feature.OrgProjectGroups(orgSlug, projectSlug): the organization group keyed by org slug and the slug group keyed by <org>/<project>, the same groups the dashboard registers.

How the server evaluates a flag

In production the SDK caches flag definitions (polled every minute) and evaluates locally, calling PostHog only for conditions it cannot decide from the distinct ID and group keys the server passes; IsFlagEnabledLocal never calls out and adds person properties. Expect up to a minute for a flip to land, stale definitions during an outage, and an Unable to compute flag locally (<key>) debug line whenever a condition needs data the server does not send.

Targeting rule for org and project flags

In the PostHog condition set, match by the organization group type and target "organization key is one of ..." (stored as $group_key); use the slug group key for project scope. Never target a group property such as organization_slug, a cohort, or person properties, except person properties a caller supplies through IsFlagEnabledLocal: the server otherwise passes group keys only, so those conditions call PostHog on every evaluation and miss most orgs, in the dashboard too.