@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/guides/using-feature-flags.mdx

@@ -0,0 +1,1059 @@
+---
+title: Using Feature Flags
+description: Complete guide to implementing feature flags in the Blue Alba Platform for controlled feature rollouts, A/B testing, and dynamic configuration
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+import MermaidDiagram from '~/components/MermaidDiagram.astro';
+
+Feature flags (also called feature toggles) are a powerful technique that allows you to control feature availability dynamically without deploying new code. The Blue Alba Platform provides a comprehensive feature flags system backed by PostgreSQL with composable conditions and typed values.
+
+## Overview
+
+The platform's feature flags system enables teams to:
+
+- **Toggle features dynamically** - Enable/disable features without redeployment
+- **Target specific users/tenants** - Release features to specific audiences
+- **Return typed values** - Flags can return any value type, not just booleans
+- **Reduce deployment risk** - Deploy code with features disabled, enable when ready
+- **Organize by application** - Associate flags with the application that owns them
+
+### Key Benefits
+
+<CardGrid stagger>
+  <Card title="Progressive Rollouts" icon="rocket">
+    Release features gradually to control risk. Use percentage-based rollout with consistent hashing to ensure users always see the same variant.
+  </Card>
+
+  <Card title="Instant Rollback" icon="setting">
+    Disable problematic features instantly without rolling back deployments or redeploying code.
+  </Card>
+
+  <Card title="Tenant Isolation" icon="lock">
+    Enable features for specific tenants while keeping them disabled for others.
+  </Card>
+
+  <Card title="Application Ownership" icon="document">
+    Associate each flag with the application that owns it, making it easier to manage and filter flags across a large platform.
+  </Card>
+</CardGrid>
+
+---
+
+## Architecture
+
+The feature flags system is a direct database-backed implementation with no provider abstraction layer. The service composes three focused collaborators — `ConditionEvaluatorService`, `RolloutService`, and `FeatureFlagsDatabaseService` — all wired together in the gateway.
+
+<MermaidDiagram
+  title="Feature Flags Architecture"
+  code={`graph TB
+    subgraph Client["Client Applications"]
+        UI[React UI<br/>useFeatureFlag]
+    end
+
+    subgraph Gateway["Gateway Service"]
+        API[Feature Flags<br/>Controller]
+        Core[Feature Flags<br/>Service]
+        Cond[Condition<br/>Evaluator]
+        Rollout[Rollout<br/>Service]
+        DB2[Database<br/>Service]
+    end
+
+    subgraph Backend["Backend Services"]
+        SVC[NestJS Service<br/>FeatureFlagsClientService<br/>@FeatureFlags decorator]
+    end
+
+    subgraph Storage["Storage"]
+        DB[(PostgreSQL<br/>Database)]
+    end
+
+    UI -->|HTTP| API
+    API --> Core
+    Core --> Cond
+    Core --> Rollout
+    Core --> DB2
+    DB2 -->|Direct| DB
+    Gateway -->|x-forwarded-feature-flags| SVC
+
+    classDef client fill:#87CEEB,color:#333
+    classDef gateway fill:#90EE90,color:#333
+    classDef storage fill:#FFD700,color:#333
+    classDef backend fill:#DDA0DD,color:#333
+
+    class UI client
+    class API,Core,Cond,Rollout,DB2 gateway
+    class SVC backend
+    class DB storage`}
+/>
+
+### Architecture Components
+
+- **Client SDKs**: React hooks library (`useFeatureFlag`, `FeatureFlagGuard`) for consuming feature flags in UI applications
+- **Backend SDKs**: NestJS utilities (`FeatureFlagsClientService`, `@FeatureFlags` decorator) from `@bluealba/pae-service-nestjs-sdk` for consuming feature flags in backend services via the `x-forwarded-feature-flags` header
+- **Gateway API**: REST endpoints for evaluating and managing feature flags
+- **Feature Flags Service**: Orchestrates evaluation logic by composing the three collaborators below
+- **Condition Evaluator**: Evaluates leaf and composite conditions against the request context
+- **Rollout Service**: Applies consistent hash-based percentage rollout gating
+- **Database Service**: Direct PostgreSQL access for reading and writing flag configurations
+
+This architecture provides:
+- **Consistency**: Same API across frontend and backend
+- **Performance**: Bulk evaluation support
+- **Self-Contained**: Requires no external services
+
+---
+
+## Core Concepts
+
+### Feature Flags
+
+A feature flag is a configuration entry that controls the value returned for a feature in a given context. Each flag has:
+
+- **name**: Unique identifier for the flag (e.g., `new-dashboard`)
+- **description**: Human-readable explanation of what the flag controls
+- **visible**: Boolean master switch; when `false` the flag is inactive and evaluation returns `null` (not `defaultValue`). The simulate endpoint returns `defaultValue` with reason `FLAG_INACTIVE` for easier debugging.
+- **defaultValue**: The value returned when no `valueRule` matches the current context
+- **valueRules**: Ordered array of rules evaluated in sequence; the first matching rule's value is returned
+- **application**: The platform application this flag belongs to (optional but strongly recommended)
+
+### Application Association
+
+Each feature flag can be associated with a specific platform application. This association:
+
+- **Identifies ownership** - Makes it clear which application or team is responsible for a flag
+- **Enables filtering** - The Admin UI allows filtering the flags list by application, which is essential when the platform hosts many flags across multiple applications
+- **Supports bootstrap** - When declaring flags in bootstrap configuration, you can reference an application by name and the platform resolves the association automatically
+
+<Aside type="tip">
+Although the `application` field is optional at the API level, assigning every feature flag to an application is strongly recommended. As the number of flags grows across the platform, the application association becomes the primary way to organize and locate flags in the Admin UI.
+</Aside>
+
+An application is identified by its **internal name** (e.g., `pae-features`) when used in bootstrap or API calls, while the Admin UI presents its **display name** (e.g., `Features`) for readability.
+
+```typescript
+interface Application {
+  id: number;
+  name: string;        // Internal application name, used in API/bootstrap
+  displayName: string; // Human-readable name, shown in Admin UI
+}
+```
+
+### Feature Flag Context
+
+When evaluating feature flags, the system uses a flat context interface to make targeting decisions. The context contains information about the current user, tenant, and any additional properties your application needs.
+
+```typescript
+interface FeatureFlagContext {
+  username?: string;   // Current username
+  tenant?: string;     // Current tenant identifier
+  [key: string]: string | number | boolean | undefined; // Additional custom attributes
+}
+```
+
+<Aside type="note">
+The context interface is intentionally flat. Unlike the legacy model there is no nested `properties` bag — custom attributes are placed directly on the context object. The special attribute name `user` in a condition maps to `context.username`.
+</Aside>
+
+### Value Rules
+
+Value rules are the targeting rules that determine what value a flag returns for a given context.
+
+**Value Rule Structure:**
+
+```typescript
+interface ValueRule {
+  name?: string;                                         // Optional human-readable identifier (improves log messages)
+  condition: LeafCondition | CompositeCondition;         // Targeting condition
+  value: any;                                           // Value to return when condition matches
+  rollout?: RolloutConfig;                              // Optional percentage-based rollout
+}
+```
+
+**How Value Rules Work:**
+
+- Rules are evaluated **in insertion order (by database `id`)** against the current context
+- The **first rule whose condition matches** wins; its `value` is returned immediately
+- If **no rule matches**, the flag's `defaultValue` is returned
+- If the flag's `visible` field is `false`, evaluation is skipped entirely and `null` is returned (not `defaultValue`)
+
+### Conditions
+
+Conditions are the building blocks of value rule targeting. There are two kinds: leaf conditions and composite conditions. They can be nested arbitrarily deep.
+
+#### Leaf Conditions
+
+A leaf condition compares a single context attribute against a value or set of values.
+
+```typescript
+interface LeafCondition {
+  attribute: string;              // Context attribute to inspect (e.g., 'tenant', 'role')
+  operator: 'eq' | 'neq' | 'in' | 'nin'; // Comparison operator
+  value: string | number | boolean | Array<string | number | boolean>;
+}
+```
+
+**Operators:**
+
+| Operator | Description | Example Use Case |
+|----------|-------------|------------------|
+| `eq` | Attribute equals value | Target a single tenant |
+| `neq` | Attribute does not equal value | Exclude a specific user |
+| `in` | Attribute is in the list | Target a set of tenants or roles |
+| `nin` | Attribute is NOT in the list | Exclude a set of users |
+
+<Aside type="note">
+The attribute name `user` is a reserved alias that maps to `context.username`. For all other attributes, the name must match a key on the `FeatureFlagContext` object.
+</Aside>
+
+**Example Leaf Condition:**
+
+```typescript
+{
+  attribute: 'tenant',
+  operator: 'in',
+  value: ['premium-tenant-1', 'premium-tenant-2']
+}
+```
+
+#### Composite Conditions
+
+Composite conditions combine multiple conditions using a logical operator. They are recursive — each entry in `rules` can itself be a leaf or another composite condition.
+
+```typescript
+interface CompositeCondition {
+  operator: 'AND' | 'OR';
+  rules: Array<LeafCondition | CompositeCondition>;
+}
+```
+
+**Example Composite Condition:**
+
+```typescript
+{
+  operator: 'AND',
+  rules: [
+    {
+      attribute: 'tenant',
+      operator: 'in',
+      value: ['premium-tenant-1', 'premium-tenant-2']
+    },
+    {
+      attribute: 'user',
+      operator: 'neq',
+      value: 'test-user@example.com'
+    }
+  ]
+}
+```
+
+This matches users in a premium tenant, excluding the test user.
+
+### Percentage-Based Rollout
+
+Value rules support an optional `rollout` configuration that restricts the rule to a percentage of the target population.
+
+```typescript
+interface RolloutConfig {
+  percentage: number; // 0–100 (inclusive)
+  attribute: string;  // Context attribute used as the hashing key
+}
+```
+
+When `rollout` is present, the rule is only applied if the SHA-256 hash of `flagName:attributeValue` falls within the given percentage bucket. This ensures:
+
+- **Consistency**: The same user always falls into the same bucket for the same flag
+- **Stability**: Adding or removing other rules does not change which bucket a user belongs to
+
+**Example — Roll out to 20% of users:**
+
+```typescript
+{
+  condition: {
+    attribute: 'tenant',
+    operator: 'eq',
+    value: 'acme-corp'
+  },
+  value: true,
+  rollout: {
+    percentage: 20,
+    attribute: 'username'
+  }
+}
+```
+
+---
+
+## Implementation Details
+
+The feature flags implementation is built directly into the gateway service. All flag configurations are stored in the gateway's PostgreSQL database and the service directly composes `FeatureFlagsDatabaseService`, `ConditionEvaluatorService`, and `RolloutService` to handle evaluation.
+
+### Capabilities
+
+- **Database-Backed Storage**: All flags stored in PostgreSQL
+- **Zero External Dependencies**: No external services required
+- **Typed Values**: Flags can return any value type, not just booleans
+- **Composable Conditions**: Leaf and composite conditions with arbitrary nesting
+- **Ordered Value Rules**: First-match-wins evaluation order (by insertion order)
+- **Percentage Rollouts**: Consistent hash-based rollout with configurable attribute
+- **Application Association**: Flags can be linked to a specific platform application
+
+### Example Feature Flag Structure
+
+Here is a complete example of a feature flag with value rules and an application association:
+
+```json
+{
+  "name": "advanced-analytics-dashboard",
+  "description": "Enable advanced analytics dashboard for specific tenants",
+  "visible": true,
+  "defaultValue": false,
+  "application": {
+    "id": 3,
+    "name": "pae-analytics",
+    "displayName": "Analytics"
+  },
+  "valueRules": [
+    {
+      "name": "premium-tenants-no-test",
+      "condition": {
+        "operator": "AND",
+        "rules": [
+          {
+            "attribute": "tenant",
+            "operator": "in",
+            "value": ["premium-tenant-1", "premium-tenant-2"]
+          },
+          {
+            "attribute": "user",
+            "operator": "neq",
+            "value": "test-user@example.com"
+          }
+        ]
+      },
+      "value": true
+    }
+  ]
+}
+```
+
+**Result**: This flag returns `true` for users in `premium-tenant-1` or `premium-tenant-2`, excluding `test-user@example.com`. All other evaluations return the `defaultValue` of `false`. It is owned by the `pae-analytics` application.
+
+---
+
+## Managing Feature Flags in the Admin UI
+
+The Platform Admin application (`pae-admin-ui`) provides a dedicated Feature Flags page where you can create, edit, and delete flags, as well as filter them by application.
+
+### Filtering by Application
+
+The Feature Flags page includes an **Application selector** in the top bar. Selecting an application filters the table to show only flags that belong to that application. The default value shows flags for all applications.
+
+This is the primary way to work with flags when a platform has many applications — each team selects their application to see only the flags they own.
+
+### Creating a Feature Flag
+
+To create a new feature flag from the Admin UI:
+
+1. Navigate to **Feature Flags** in the Admin application.
+2. Click **Add Feature Flag**.
+3. Fill in the required fields in the dialog:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| **Name** | Yes | Unique identifier. Kebab-case, no spaces (e.g., `new-checkout-flow`). Cannot be changed after creation. |
+| **Application** | Yes | The platform application this flag belongs to. |
+| **Description** | No | Human-readable explanation of what the flag controls. |
+| **Visible** | Yes | Master switch. When off, evaluation always returns the default value. Defaults to `true`. |
+| **Default Value** | No | Value returned when no value rule matches. |
+| **Value Rules** | No | Ordered targeting rules; the first matching rule's value is returned. |
+
+4. Click **Create** to save the flag.
+
+<Aside type="note">
+The **Application** field is required in the Admin UI form. This ensures every flag created through the UI is properly organized and discoverable.
+</Aside>
+
+### Editing a Feature Flag
+
+To edit an existing flag:
+
+1. Locate the flag in the table (use the Application selector or the search input to narrow down results).
+2. Click the actions menu (three-dot icon) on the flag row.
+3. Select **Edit**.
+4. Update any field except **Name** (the name is immutable after creation).
+5. Click **Save Changes**.
+
+<Aside type="caution">
+When you save an edit that includes changes to value rules, **all existing value rules are replaced** by the new set. This is an atomic replacement, not a merge. If you clear all value rules, the flag will always return its `defaultValue`.
+</Aside>
+
+### Searching and Filtering
+
+The Feature Flags table provides two ways to narrow down results:
+
+- **Application selector** (top bar): Filters flags by their associated application. Selecting "All Applications" shows every flag regardless of association.
+- **Search input** (above the table): Filters flags whose name or description match the search term.
+
+Both filters are applied simultaneously, so you can select an application and then search within it.
+
+---
+
+## Declaring Feature Flags via Bootstrap
+
+The bootstrap mechanism allows applications to declare their required feature flags as code, ensuring they are created (or updated) automatically when the platform initializes. This is the recommended way to manage flags for an application — it makes the flag definitions version-controlled and reproducible.
+
+For the full reference on configuring `feature-flags.json`, including examples and upsert semantics, see the [Bootstrap Architecture documentation](/_/docs/architecture/bootstrap/#feature-flags-definition).
+
+### Direct API Usage
+
+You can also manage flags directly via the gateway REST API (internal endpoint secured at the network level under `/_/`).
+
+<Tabs>
+  <TabItem label="Create flag">
+```bash
+POST /_/feature-flags
+Content-Type: application/json
+
+{
+  "name": "new-checkout-flow",
+  "description": "Enable the redesigned checkout experience",
+  "visible": true,
+  "defaultValue": false,
+  "applicationId": 5,
+  "valueRules": [
+    {
+      "name": "premium-tenants",
+      "condition": {
+        "attribute": "tenant",
+        "operator": "in",
+        "value": ["premium-tenant-1", "premium-tenant-2"]
+      },
+      "value": true
+    }
+  ]
+}
+```
+
+`valueRules` is optional. If omitted, the flag is created with no rules and every evaluation returns `defaultValue`.
+  </TabItem>
+  <TabItem label="Update flag with value rules">
+```bash
+PATCH /_/feature-flags/new-checkout-flow
+Content-Type: application/json
+
+{
+  "visible": true,
+  "defaultValue": false,
+  "valueRules": [
+    {
+      "name": "premium-tenants",
+      "condition": {
+        "attribute": "tenant",
+        "operator": "in",
+        "value": ["premium-tenant-1", "premium-tenant-2"]
+      },
+      "value": true
+    },
+    {
+      "name": "admin-internal-50pct",
+      "condition": {
+        "operator": "AND",
+        "rules": [
+          { "attribute": "role", "operator": "eq", "value": "admin" },
+          { "attribute": "tenant", "operator": "eq", "value": "internal" }
+        ]
+      },
+      "value": true,
+      "rollout": {
+        "percentage": 50,
+        "attribute": "username"
+      }
+    }
+  ]
+}
+```
+  </TabItem>
+  <TabItem label="Get all flags">
+```bash
+GET /_/feature-flags/all
+```
+
+Each flag in the response includes `visible`, `defaultValue`, `valueRules`, and an optional `application` object:
+
+```json
+[
+  {
+    "id": 12,
+    "name": "new-checkout-flow",
+    "description": "Enable the redesigned checkout experience",
+    "visible": true,
+    "defaultValue": false,
+    "application": {
+      "id": 5,
+      "name": "pae-commerce",
+      "displayName": "Commerce"
+    },
+    "valueRules": [],
+    "createdAt": "2026-01-10T09:00:00Z",
+    "updatedAt": "2026-01-10T09:00:00Z"
+  }
+]
+```
+  </TabItem>
+  <TabItem label="Evaluate a flag">
+```bash
+POST /_/feature-flags/evaluate/new-checkout-flow
+```
+
+This endpoint takes **no request body**. The evaluation context (username, tenant, role) is derived from the authenticated user associated with the request. To test arbitrary contexts without being tied to an authenticated user, use the simulate endpoint instead.
+
+Response:
+
+```json
+{
+  "flagName": "new-checkout-flow",
+  "value": true,
+  "evaluatedAt": "2026-01-10T09:00:00Z"
+}
+```
+  </TabItem>
+  <TabItem label="Get flag details">
+```bash
+GET /_/feature-flags/new-checkout-flow
+```
+
+Returns full details of a single flag including all value rules and application association.
+
+Response:
+
+```json
+{
+  "id": 12,
+  "name": "new-checkout-flow",
+  "description": "Enable the redesigned checkout experience",
+  "visible": true,
+  "defaultValue": false,
+  "application": {
+    "id": 5,
+    "name": "pae-commerce",
+    "displayName": "Commerce"
+  },
+  "valueRules": [
+    {
+      "id": 1,
+      "name": "premium-tenants",
+      "condition": {
+        "attribute": "tenant",
+        "operator": "in",
+        "value": ["premium-tenant-1", "premium-tenant-2"]
+      },
+      "value": true,
+      "rollout": null,
+      "createdAt": "2026-01-10T09:00:00Z",
+      "updatedAt": "2026-01-10T09:00:00Z"
+    }
+  ],
+  "createdAt": "2026-01-10T09:00:00Z",
+  "updatedAt": "2026-01-10T09:00:00Z",
+  "createdBy": "admin",
+  "updatedBy": "admin"
+}
+```
+  </TabItem>
+  <TabItem label="Simulate evaluation">
+```bash
+POST /_/feature-flags/simulate/new-checkout-flow
+Content-Type: application/json
+
+{
+  "context": {
+    "username": "alice@example.com",
+    "tenant": "premium-tenant-1",
+    "role": "user"
+  }
+}
+```
+
+The context is supplied directly in the request body and is **not** derived from the authenticated user. This makes the endpoint safe for arbitrary testing during development.
+
+Response (rule matched):
+
+```json
+{
+  "flagName": "new-checkout-flow",
+  "active": true,
+  "value": true,
+  "reason": "RULE_MATCHED",
+  "matchedRule": {
+    "name": "premium-tenants",
+    "condition": {
+      "attribute": "tenant",
+      "operator": "in",
+      "value": ["premium-tenant-1", "premium-tenant-2"]
+    },
+    "value": true,
+    "rollout": null
+  },
+  "evaluatedAt": "2026-01-10T09:00:00Z",
+  "context": {
+    "username": "alice@example.com",
+    "tenant": "premium-tenant-1",
+    "role": "user"
+  }
+}
+```
+  </TabItem>
+  <TabItem label="Bulk evaluate">
+```bash
+POST /_/feature-flags/evaluate
+Content-Type: application/json
+
+{
+  "flagNames": ["new-checkout-flow", "beta-reporting", "new-dashboard-ui"],
+  "customProperties": {
+    "experimentGroup": "b"
+  }
+}
+```
+
+Evaluates multiple flags in a single request. `flagNames` is required; `customProperties` is an optional map of additional context attributes to merge into the evaluation context.
+
+Response:
+
+```json
+{
+  "flags": {
+    "new-checkout-flow": true,
+    "beta-reporting": false,
+    "new-dashboard-ui": null
+  },
+  "evaluatedAt": "2026-01-10T09:00:00Z"
+}
+```
+  </TabItem>
+  <TabItem label="Delete flag">
+```bash
+DELETE /_/feature-flags/new-checkout-flow
+```
+
+Deletes the feature flag and all its associated value rules. This operation is permanent.
+
+Response:
+
+```json
+{
+  "name": "new-checkout-flow",
+  "deletedAt": "2026-01-10T09:00:00Z",
+  "message": "Feature flag \"new-checkout-flow\" has been permanently deleted"
+}
+```
+  </TabItem>
+</Tabs>
+
+---
+
+## Simulating Feature Flag Evaluation
+
+The simulate endpoint (`POST /_/feature-flags/simulate/:flagName`) is a development and debugging tool that lets you test how a flag evaluates for any arbitrary context without being tied to the authenticated user.
+
+### Evaluate vs Simulate
+
+| Aspect | `POST /evaluate/:flagName` | `POST /simulate/:flagName` |
+|--------|---------------------------|---------------------------|
+| **Context source** | Authenticated user (derived server-side) | Request body `{ context: {...} }` |
+| **Error on missing flag** | Returns `null` | Returns `FLAG_NOT_FOUND` reason |
+| **Response detail** | Value only | Value + reason + matched rule + echoed context |
+| **Non-visible flag** | Returns `null` | Returns `defaultValue` with `FLAG_INACTIVE` reason |
+| **Intended use** | Production evaluation | Development / rule debugging |
+
+### SimulationReason Values
+
+| Reason | When returned |
+|--------|---------------|
+| `FLAG_NOT_FOUND` | No flag with the given name exists in the database |
+| `FLAG_INACTIVE` | The flag exists but `visible` is `false` |
+| `RULE_MATCHED` | A value rule's condition matched the provided context |
+| `DEFAULT_VALUE` | The flag is visible but no rule matched; `defaultValue` is returned |
+
+### Example — Rule Matched
+
+```bash
+POST /_/feature-flags/simulate/beta-reporting
+Content-Type: application/json
+
+{
+  "context": {
+    "username": "beta-user-1@example.com",
+    "tenant": "acme-corp"
+  }
+}
+```
+
+```json
+{
+  "flagName": "beta-reporting",
+  "active": true,
+  "value": true,
+  "reason": "RULE_MATCHED",
+  "matchedRule": {
+    "name": "beta-user-access",
+    "condition": {
+      "attribute": "user",
+      "operator": "in",
+      "value": ["beta-user-1@example.com", "beta-user-2@example.com"]
+    },
+    "value": true,
+    "rollout": null
+  },
+  "evaluatedAt": "2026-01-10T09:00:00Z",
+  "context": {
+    "username": "beta-user-1@example.com",
+    "tenant": "acme-corp"
+  }
+}
+```
+
+### Example — No Rule Matched (Default Value Returned)
+
+```bash
+POST /_/feature-flags/simulate/beta-reporting
+Content-Type: application/json
+
+{
+  "context": {
+    "username": "regular-user@example.com",
+    "tenant": "acme-corp"
+  }
+}
+```
+
+```json
+{
+  "flagName": "beta-reporting",
+  "active": true,
+  "value": false,
+  "reason": "DEFAULT_VALUE",
+  "matchedRule": null,
+  "evaluatedAt": "2026-01-10T09:00:00Z",
+  "context": {
+    "username": "regular-user@example.com",
+    "tenant": "acme-corp"
+  }
+}
+```
+
+<Aside type="tip">
+Use the simulate endpoint during development to verify your targeting rules before deploying. You can test any combination of context attributes without needing to log in as different users, making it straightforward to confirm that conditions like `in`, `AND`, or percentage rollouts work as intended.
+</Aside>
+
+---
+
+## Usage in React Applications
+
+The platform provides React hooks and components for easy feature flag integration in UI applications.
+
+### Setup
+
+**1. Install the SDK:**
+
+The SDK is included in the `pae-ui-react-core` package.
+
+### Reading Flag Values with useFeatureFlag
+
+The `useFeatureFlag` hook returns the evaluated value of a flag for the current user context. Because flags can now return any type, the hook returns `any`.
+
+```typescript
+import { useFeatureFlag } from '@bluealba/pae-ui-react-core';
+
+function MyComponent() {
+  const isNewDashboardEnabled = useFeatureFlag('new-dashboard');
+
+  return (
+    <div>
+      {isNewDashboardEnabled ? (
+        <NewDashboard />
+      ) : (
+        <LegacyDashboard />
+      )}
+    </div>
+  );
+}
+```
+
+**Hook Signature:**
+
+```typescript
+function useFeatureFlag(flagName: string): any
+```
+
+**Parameters:**
+- `flagName`: Name of the feature flag to evaluate
+
+**Returns:**
+- `any`: The evaluated flag value. For boolean flags this will be `true` or `false`; for typed flags it will be whatever value the matching rule specifies. Returns `undefined` when the flag is not present in the bootstrapped flags map.
+
+**Example with a string-valued flag:**
+
+```typescript
+function ThemeSelector() {
+  const theme = useFeatureFlag('ui-theme'); // returns 'light', 'dark', 'system', or undefined
+
+  return <AppShell theme={theme ?? 'light'} />;
+}
+```
+
+### Conditional Rendering with FeatureFlagGuard
+
+`FeatureFlagGuard` renders its children only when the evaluated flag value is strictly `true`. It is designed for boolean flags used as on/off guards.
+
+```typescript
+import { FeatureFlagGuard } from '@bluealba/pae-ui-react-core';
+
+function MyComponent() {
+  return (
+    <div>
+      <h1>My App</h1>
+
+      <FeatureFlagGuard flag="beta-features" fallback={<ComingSoon />}>
+        <BetaFeatures />
+      </FeatureFlagGuard>
+
+      <FeatureFlagGuard flag="premium-analytics">
+        <PremiumAnalytics />
+      </FeatureFlagGuard>
+    </div>
+  );
+}
+```
+
+**Component Props:**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `flag` | string | Yes | Name of the feature flag |
+| `fallback` | ReactNode | No | Content to show when flag value is not `true` |
+| `children` | ReactNode | Yes | Content to show when flag value is strictly `true` |
+| `invert` | boolean | No | When `true`, shows children when the flag is disabled and `fallback` when enabled. Defaults to `false`. |
+
+<Aside type="note">
+`FeatureFlagGuard` uses a strict equality check (`=== true`). If your flag returns a truthy non-boolean value (e.g., a non-empty string), the children will not render. Use `useFeatureFlag` directly and write your own condition for non-boolean flags.
+</Aside>
+
+---
+
+## Usage in NestJS Backend Services
+
+The gateway evaluates all feature flags for the current user before forwarding any proxied request to a microservice, and injects the results as the `x-forwarded-feature-flags` header (base64-encoded JSON). The `@bluealba/pae-service-nestjs-sdk` package exposes utilities to read those flags — no additional HTTP calls required.
+
+### Setup
+
+Add `FeatureFlagsClientModule` to the `imports` array of the NestJS module where you need flag access:
+
+```typescript
+import { FeatureFlagsClientModule } from '@bluealba/pae-service-nestjs-sdk';
+import { Module } from '@nestjs/common';
+import { AcmeController } from './acme.controller';
+import { AcmeService } from './acme.service';
+
+@Module({
+  imports: [FeatureFlagsClientModule],
+  controllers: [AcmeController],
+  providers: [AcmeService],
+})
+export class AcmeModule {}
+```
+
+### Option 1 — Injectable Service
+
+Inject `FeatureFlagsClientService` into any provider that has access to the request object:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { FeatureFlagsClientService } from '@bluealba/pae-service-nestjs-sdk';
+import { FastifyRequest } from 'fastify';
+
+@Injectable()
+export class AcmeService {
+  constructor(private readonly featureFlags: FeatureFlagsClientService) {}
+
+  async getItems(req: FastifyRequest) {
+    const isNewUI = this.featureFlags.get<boolean>(req, 'new-ui') ?? false;
+    const pageSize = this.featureFlags.get<number>(req, 'items-page-size') ?? 20;
+    // ...
+  }
+}
+```
+
+**API:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getAll` | `getAll(req): Record<string, any>` | Returns all evaluated flags for the request |
+| `get` | `get<T>(req, flagName): T \| undefined` | Returns the value of a specific flag, or `undefined` if not present |
+
+### Option 2 — Parameter Decorator in Controllers
+
+Use `@FeatureFlags()` to bind flag values directly to controller method parameters:
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { FeatureFlags } from '@bluealba/pae-service-nestjs-sdk';
+
+@Controller('acme')
+export class AcmeController {
+  @Get()
+  async getItems(@FeatureFlags('new-ui') isNewUI: boolean) {
+    // isNewUI is the evaluated value of the 'new-ui' flag for this user
+  }
+
+  @Get('debug')
+  async debugFlags(@FeatureFlags() flags: Record<string, any>) {
+    return { flags };
+  }
+}
+```
+
+| Usage | Resolves to |
+|-------|-------------|
+| `@FeatureFlags()` | `Record<string, any>` — all evaluated flags |
+| `@FeatureFlags('flag-name')` | `T \| undefined` — value of the named flag |
+
+<Aside type="caution">
+Do not use feature flags as security gates. Flags are forwarded from the gateway at request time but are not re-validated by the microservice. Use the platform's authorization system (roles and operations) for access control.
+</Aside>
+
+---
+
+## Best Practices
+
+### When to Use Feature Flags
+
+<CardGrid stagger>
+  <Card title="New Features" icon="rocket">
+    Use release flags for new features to control rollout and enable quick rollback if issues arise.
+  </Card>
+
+  <Card title="Kill Switches" icon="warning">
+    Use kill-switch flags for critical systems that may need instant disabling. Set `visible: false` to immediately short-circuit evaluation.
+  </Card>
+
+  <Card title="Permissions" icon="lock">
+    Use permission flags to control feature access based on user role or tenant.
+  </Card>
+</CardGrid>
+
+**When NOT to use feature flags:**
+- For every small code change (flag sprawl)
+- As a replacement for configuration management
+- For security-sensitive features that should be removed entirely
+- When the code complexity becomes unmanageable
+
+### Always Associate Flags with an Application
+
+Every feature flag should be linked to the application that owns it, using `applicationId` (via API) or `applicationName` (via bootstrap). This practice:
+
+- Keeps the Feature Flags page navigable as the platform scales
+- Makes it immediately clear which team is responsible for a flag
+- Enables accurate filtering in the Admin UI
+
+### Order Value Rules from Most Specific to Least Specific
+
+Because evaluation stops at the first matching rule, place the most targeted rules at the top of the `valueRules` array. A broad catch-all rule at the end acts as a secondary default.
+
+```typescript
+// Good — specific rules first, broad rule last
+valueRules: [
+  {
+    name: 'admin-preview',
+    condition: { attribute: 'user', operator: 'eq', value: 'admin@example.com' },
+    value: 'admin-preview'   // Exact user gets a special value
+  },
+  {
+    name: 'beta-access',
+    condition: { attribute: 'role', operator: 'eq', value: 'beta' },
+    value: true              // Beta role gets the feature
+  }
+  // No further rules — all other users fall through to defaultValue
+]
+```
+
+### Use the visible Field as a Master Switch
+
+Set `visible: false` to immediately deactivate a flag without deleting it or clearing its value rules. This is the safest way to perform an emergency rollback — re-enabling a flag is a single field update.
+
+### Naming Conventions
+
+Use consistent, descriptive names for your feature flags:
+
+**Recommended Formats:**
+
+```
+# Feature releases
+new-[feature-name]
+enable-[feature-name]
+[feature-name]-v2
+
+# Examples
+new-dashboard-ui
+enable-advanced-search
+checkout-flow-v2
+
+# Experiments
+[feature]-[experiment-name]
+ab-test-[feature]
+
+# Examples
+checkout-express-flow
+ab-test-pricing-page
+
+# Kill switches
+[system]-enabled
+[integration]-active
+
+# Examples
+payment-processing-enabled
+analytics-tracking-active
+```
+
+**Best Practices:**
+- Use kebab-case (lowercase with hyphens)
+- Be descriptive but concise
+- Include feature area in the name
+- Avoid generic names like `feature1` or `test`
+
+---
+
+## Summary
+
+The Blue Alba Platform's feature flags system provides a powerful, flexible way to control feature availability in your applications. Key takeaways:
+
+<CardGrid stagger>
+  <Card title="Rules-Based Evaluation" icon="approve-check">
+    Flags use an ordered `valueRules` array. The first matching rule wins; `defaultValue` is the fallback.
+  </Card>
+
+  <Card title="Composable Conditions" icon="magnifier">
+    Combine leaf conditions (`eq`, `neq`, `in`, `nin`) with `AND`/`OR` composites to express any targeting logic.
+  </Card>
+
+  <Card title="Self-Contained" icon="rocket">
+    Requires only PostgreSQL — no external services needed.
+  </Card>
+
+  <Card title="Application-Scoped" icon="document">
+    Associate flags with applications to keep large flag sets organized and filterable.
+  </Card>
+</CardGrid>
+
+<Aside type="tip">
+Keep in mind that you can manage the feature flags in the platform admin application. Use the Application selector at the top of the Feature Flags page to filter flags by the application that owns them.
+</Aside>
+
+**Next Steps:**
+1. Create your first feature flag and assign it to an application
+2. Declare flags in your application's bootstrap configuration using `applicationName` and `valueRules`
+3. Integrate the React SDK using `useFeatureFlag` or `FeatureFlagGuard`
+4. In NestJS microservices, import `FeatureFlagsClientModule` and use `FeatureFlagsClientService` or `@FeatureFlags()`
+5. Start using feature flags to control rollouts safely
+
+For questions or issues, reach out to the platform team.