Feature Flags & Toggles

Relevant source files

The following files were used as context for generating this wiki page:

• packages/flags/src/service.ts
• packages/db/prisma/schema.prisma
• packages/db/prisma/migrations/20260531091720_init/migration.sql
• README.md
• apps/web/package.json

The Feature Flags & Toggles system provides a robust, database-backed mechanism for controlling the availability of specific application features without requiring redeployments. It is designed with a decentralized in-process caching strategy that ensures high performance while adhering to a 5-minute Service Level Agreement (SLA) for flag consistency across replicas.

Sources: packages/flags/src/service.ts:1-12, README.md:160-161

System Architecture

The feature flag architecture centers around the FeatureFlagService, which interacts with the PostgreSQL database through Prisma. Each application replica maintains its own local, independent cache to minimize database load during frequent flag checks.

Component Interaction

The following diagram illustrates the data flow when an application component requests a feature flag status.

The system ensures that a warm cache results in a simple O(1) lookup, while a cache miss triggers a database query followed by a deterministic evaluation of the flag's state.

Sources: packages/flags/src/service.ts:52-64, README.md:143-145

Data Model

Feature flags are persisted in the FeatureFlag table. This model supports global toggles, targeted rollouts via percentages, and specific overrides for individual installations.

Field	Type	Description
key	String	Unique identifier for the flag (e.g., billing.enforcement).
enabled	Boolean	Global default state of the flag.
rolloutPercent	Integer	0–100 value for deterministic percentage-based rollouts.
overrides	JSONB	Map of installationId to Boolean for explicit targeting.

Sources: packages/db/prisma/schema.prisma:243-255, packages/db/prisma/migrations/20260531091720_init/migration.sql:149-158

Evaluation Logic

The FeatureFlagService evaluates flags using a specific hierarchy of precedence to determine the final boolean state for a given context (typically an installationId).

Resolution Order

1. Explicit Overrides: If the installationId is present in the overrides JSON object, that value is used immediately.
2. Rollout Percentage: If no override exists, a deterministic hash is generated from the installationId. If the resulting bucket (0-99) is less than the rolloutPercent, the feature is enabled.
3. Global Default: If neither of the above applies, the enabled boolean field is returned.

Sources: packages/flags/src/service.ts:98-121

Deterministic Rollout Implementation

The rollout mechanism uses SHA-256 hashing to ensure that an installation consistently remains in or out of a feature group, preventing "flapping" behavior.

function percentBucket(id: string): number {
  const hash = createHash('sha256').update(id).digest();
  const n = hash.readUInt32BE(0);
  return n % 100;
}

Sources: packages/flags/src/service.ts:127-132

Caching and Performance

To meet performance requirements, the service implements a 5-minute in-process cache.

• Cache TTL: Fixed at 300,000ms (5 minutes).
• Decentralization: Each replica manages its own cache; there is no cross-replica coordination or shared Redis layer.
• Invalidation: The invalidate(key) method allows forcing a re-read from the database, which is typically triggered by admin actions to ensure immediate consistency on the local replica.

Sources: packages/flags/src/service.ts:35-42, packages/flags/src/service.ts:71-84

Defined Feature Flags

The application defines specific functional flags within the FlagKeys constant to ensure type safety and ease of discovery within the codebase.

Key	DB String	Purpose
BillingEnforcement	billing.enforcement	Controls rate limits and paywall enforcement.
IngestionParallel	ingestion.parallel	Enables multiple PR hydration jobs per installation.
RetrievalRerank	retrieval.rerank	Toggles the cross-encoder rerank step in RAG retrieval.
UISimilarIncidents	ui.similar_incidents	Controls the posting of "similar incidents" comments on issues.

Sources: packages/flags/src/service.ts:21-30

Integration with Services

The feature flag package (@repo/flags) is a shared dependency used across the workspace.

{
  "dependencies": {
    "@repo/db": "*",
    "@repo/flags": "*",
    "@repo/services": "*"
  }
}

The web application and other services utilize the FeatureFlagService to gate business logic, such as enabling parallel ingestion or enforcing subscription-based limits.

Sources: apps/web/package.json:20-22, README.md:38-39