Feature Flags

The gateway conditionally mounts services based on a feature flag system. This allows individual services to be enabled or disabled without code changes, controlled entirely through environment variables.

How It Works

Feature flags are defined in @shift/platform-core/features. Each flag has a key, a description, a default state, and a corresponding environment variable. At startup, the gateway checks each flag and only mounts services whose flags are enabled.

The resolution order for each flag is:

1. Environment variable (highest priority) -- e.g., SHIFT_FEATURE_PULSE=0 disables Pulse regardless of other settings.
2. Runtime override -- Set programmatically via setFeatureOverrides() (reserved for future per-org gating).
3. Default value -- The hardcoded default in the feature definition.

Environment variable values of "0" or "false" (case-insensitive) disable the flag. Any other value enables it.

Feature Definitions

Key	Env Var	Default	Description
yellowpages	SHIFT_FEATURE_YELLOWPAGES	Enabled	Service catalog
passport	SHIFT_FEATURE_PASSPORT	Enabled	Auth and identity
pulse	SHIFT_FEATURE_PULSE	Enabled	Monitoring and telemetry
ledger	SHIFT_FEATURE_LEDGER	Enabled	Data governance
stage	SHIFT_FEATURE_STAGE	Enabled	Deployment sandbox
palette	SHIFT_FEATURE_PALETTE	Enabled	Design system
communication	SHIFT_FEATURE_COMMUNICATION	Disabled	Communication API
inference	SHIFT_FEATURE_INFERENCE	Disabled	AI inference routing
compute	SHIFT_FEATURE_COMPUTE	Enabled	Backend compute modules
billing	SHIFT_FEATURE_BILLING	Disabled	Cost tracking and billing
git	SHIFT_FEATURE_GIT	Disabled	Git repository management

What Gets Gated

When a service's feature flag is disabled:

• Its createApp() factory is never called.
• Its API routes are not registered on the gateway.
• Its SPA fallback routes are not configured.
• It is excluded from the aggregated /api/v1/health check.

Requests to a disabled service's API prefix return a generic 404 JSON response from the gateway's catch-all handler.

Stage Proxy as Feature Configuration

The STAGE_PROXY_URL environment variable is a related but distinct configuration. It does not enable or disable Stage (that is controlled by SHIFT_FEATURE_STAGE). Instead, it changes Stage's behavior from in-process handling to external proxying. When set, the gateway forwards Stage API requests to the specified URL, falling back to the in-process handler if the proxy is unreachable. See Gateway for details.

Diagnostics Endpoint

The gateway exposes GET /api/v1/features which returns the full state of every feature flag, including its current enabled/disabled state and the resolution source (env, override, or default):

{
  "success": true,
  "data": [
    { "key": "yellowpages", "enabled": true, "source": "default", "description": "Service catalog" },
    { "key": "communication", "enabled": false, "source": "default", "description": "Communication API" },
    { "key": "pulse", "enabled": true, "source": "env", "description": "Monitoring & telemetry" }
  ]
}

This endpoint is available before auth middleware, so it can be queried without authentication.