# How OmniRoute Defines and Manages Feature Flags Across Security, Network, and Runtime Categories

> Learn how OmniRoute manages feature flags across security, network, and runtime. Discover its centralized system with a three-tier priority chain for dynamic toggling without redeployment.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: architecture
- Published: 2026-07-14

---

**OmniRoute implements a centralized feature flag system in [`src/shared/utils/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/featureFlags.ts) that resolves values via a three-tier priority chain: database overrides first, environment variables second, and hard-coded defaults last, enabling dynamic toggling of security guardrails, network proxies, and runtime behaviors without redeployment.**

The open-source OmniRoute project (diegosouzapw/OmniRoute) uses a unified feature flag architecture to control behavior across three logical layers. Every flag follows the same resolution pattern, allowing operators to override defaults through a database-backed dashboard or environment variables while maintaining type safety through a centralized TypeScript registry.

## Centralized Feature Flag Architecture

At the heart of the system lies [`src/shared/utils/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/featureFlags.ts), which exports a strongly typed map called `FEATURE_FLAGS`. This registry defines every valid flag key, its default value, description, and category classification. The resolution logic treats all flags uniformly regardless of category, ensuring consistent behavior whether the flag controls a security policy or a network transport.

The resolution hierarchy follows strict precedence:

1. **Database override** (highest priority) – Stored in the `feature_flags` table via [`src/lib/db/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/featureFlags.ts)
2. **Environment variable** – Parsed from `process.env.OMNIROUTE_<UPPERCASE_KEY>`
3. **Hard-coded default** – Defined in the `FEATURE_FLAGS` map

## Feature Flag Categories

While the resolution engine is category-agnostic, flags are logically grouped into Security, Network, and Runtime buckets for documentation and operational clarity.

### Security Flags

Security flags control guardrails, PII handling, API-key policies, and authentication checks. These are declared in the central registry but often referenced in middleware layers.

For example, the `INJECTION_GUARD_MODE` flag (default `"off"`) is resolved in [`src/middleware/promptInjectionGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts) using `isFeatureEnabled()`. When enabled via a database override or environment variable, the middleware activates prompt injection detection. This allows security teams to enable protections in production without code changes, or to emergency-disable them if false positives occur.

### Network Flags

Network flags govern proxy handling, fallback transports, WebSocket kill-switches, and stream-recovery behavior. These are consumed by transport-layer utilities throughout the `open-sse/` directory.

The `PROXY_SOCKS5_ENABLED` flag (default `false`) demonstrates this pattern in [`open-sse/utils/proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFetch.ts). The code checks the flag before honoring SOCKS5 proxy configurations:

```typescript
import { isFeatureEnabled } from "@/shared/utils/featureFlags";

if (isFeatureEnabled("PROXY_SOCKS5_ENABLED")) {
  // Enable SOCKS5 proxy handling
}

```

Similarly, the Codex WebSocket kill-switch in [`open-sse/executors/codex.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/codex.ts) uses these utilities to short-circuit connections when flags are disabled.

### Runtime Flags

Runtime flags affect the request pipeline, including PII transforms, commentary dropping, combo-routing, and compression modes. These are frequently accessed during request processing.

The `RESPONSES_PASSTHROUGH_DROP_COMMENTARY` and `STREAM_RECOVERY_ENABLED` flags (both defined in [`src/shared/utils/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/featureFlags.ts)) control how the system processes response streams. Their defaults are seeded in [`src/lib/resilience/settings/types.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/resilience/settings/types.ts), which uses the resolved values to configure resilience policies.

## Core Implementation Details

### Typed Flag Definitions

The `FEATURE_FLAGS` object in [`src/shared/utils/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/featureFlags.ts) provides compile-time safety through TypeScript's `satisfies` operator:

```typescript
export const FEATURE_FLAGS = {
  STREAM_RECOVERY_ENABLED: {
    description: "Enable stream‑recovery resilience defaults",
    default: true,
    category: "runtime",
  },
  PROXY_SOCKS5_ENABLED: {
    description: "Enable SOCKS5 proxy support",
    default: false,
    category: "network",
  },
  // ... additional flags
} satisfies Record<string, FeatureFlagMeta>;

```

The `category` field serves documentation purposes, while the actual logic treats all flags uniformly.

### Resolution Logic and Priority

The `resolveFeatureFlag(key)` function implements the three-tier fallback mechanism. It returns both the resolved value and a `source` string indicating the origin (`"db"`, `"env"`, or `"default"`):

```typescript
import { resolveFeatureFlag } from "@/shared/utils/featureFlags";

const { value, source } = resolveFeatureFlag("STREAM_RECOVERY_ENABLED");
console.log(`Stream recovery is ${value ? "ON" : "OFF"} (source: ${source})`);

```

This origin tracking powers the Settings API's transparency features, allowing administrators to see why a particular value is active.

### Database Overrides and API

The [`src/lib/db/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/featureFlags.ts) module implements CRUD operations for persistent overrides:

- `setFeatureFlag(key, value)` – Writes to the `feature_flags` table
- `getFeatureFlagOverrides()` – Returns all active overrides as a map
- `clearAllFeatureFlags()` – Removes all rows (used for admin resets)

These operations are exposed via [`src/app/api/settings/feature-flags/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/settings/feature-flags/route.ts), enabling the dashboard to modify flags without redeployment. The API validates inputs against the `FEATURE_FLAGS` registry to prevent invalid keys.

### Environment Variable Fallbacks

For CI/CD pipelines and containerized deployments, flags can be set via environment variables following the pattern `OMNIROUTE_<UPPERCASE_KEY>`. The resolver parses these as booleans (`"true"`/`"false"` strings) when no database override exists.

## Practical Usage Patterns

Components access flags through two primary helpers exported from [`src/shared/utils/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/featureFlags.ts):

**Boolean checks for conditional logic:**

```typescript
import { isFeatureEnabled } from "@/shared/utils/featureFlags";

if (isFeatureEnabled("RESPONSES_PASSTHROUGH_DROP_COMMENTARY")) {
  // Drop commentary events from the Responses API stream
}

```

**Full resolution with source tracking:**

```typescript
const { value, source } = resolveFeatureFlag("PROXY_SOCKS5_ENABLED");
// value: boolean, source: "db" | "env" | "default"

```

**Admin override via Settings API:**

```typescript
// POST /api/settings/feature-flags
// Body: { "key": "INJECTION_GUARD_MODE", "value": "strict" }

```

**Clearing all overrides:**

```typescript
import { clearAllFeatureFlags } from "@/lib/db/featureFlags";
await clearAllFeatureFlags(); // Removes all DB overrides, reverting to defaults

```

## Summary

- OmniRoute uses a **centralized registry** in [`src/shared/utils/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/featureFlags.ts) that defines all valid flags with TypeScript types, defaults, and categories.
- **Resolution follows strict priority**: database overrides take precedence over environment variables (`OMNIROUTE_*`), which take precedence over hard-coded defaults.
- **Security flags** (e.g., `INJECTION_GUARD_MODE`) control middleware guardrails in [`src/middleware/promptInjectionGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts).
- **Network flags** (e.g., `PROXY_SOCKS5_ENABLED`) govern transport behavior in [`open-sse/utils/proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFetch.ts) and executor modules.
- **Runtime flags** (e.g., `STREAM_RECOVERY_ENABLED`) configure request pipeline behavior and resilience settings.
- The **database layer** ([`src/lib/db/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/featureFlags.ts)) and **Settings API** ([`src/app/api/settings/feature-flags/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/settings/feature-flags/route.ts)) enable dynamic runtime changes without redeployment.

## Frequently Asked Questions

### How does OmniRoute prioritize feature flag values when multiple sources define them?

OmniRoute resolves feature flags using a three-tier priority system implemented in `resolveFeatureFlag()`. Database overrides stored via [`src/lib/db/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/featureFlags.ts) always win. If no database row exists, the system checks for an environment variable matching `OMNIROUTE_<UPPERCASE_KEY>`. Only if both are absent does it fall back to the hard-coded default from `FEATURE_FLAGS`. The function returns a `source` property indicating which tier provided the value.

### Can feature flags be changed at runtime without restarting the server?

Yes. Flags stored in the database are read dynamically through the `getFeatureFlagOverrides()` function. The Settings API endpoint at [`src/app/api/settings/feature-flags/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/settings/feature-flags/route.ts) allows authorized users to update values via HTTP requests, and subsequent calls to `isFeatureEnabled()` or `resolveFeatureFlag()` immediately reflect the new values. Environment variables and hard-coded defaults require a restart to change.

### What is the difference between `isFeatureEnabled()` and `resolveFeatureFlag()`?

`isFeatureEnabled(key)` returns only the boolean resolved value, making it ideal for conditional logic like `if (isFeatureEnabled("PROXY_SOCKS5_ENABLED"))`. `resolveFeatureFlag(key)` returns an object containing both the `value` and the `source` string (`"db"`, `"env"`, or `"default"`), which is useful for logging, debugging, or dashboard UI that needs to show why a flag has its current value.

### How are new feature flags added to the OmniRoute codebase?

Developers add entries to the `FEATURE_FLAGS` object in [`src/shared/utils/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/featureFlags.ts). Each entry requires a `description`, `default` value, and `category` field. Once defined, the flag can be consumed anywhere in the codebase using the typed helpers. Because the system uses TypeScript's `satisfies Record<string, FeatureFlagMeta>`, the compiler ensures all flag keys remain consistent across the application.