ADR-024 Feature Flagging Strategy

docs/plans/2026-01-28-adr-024-feature-flags-implementation.md

@@ -0,0 +1,849 @@
+# ADR-024 Implementation Plan: Feature Flagging Strategy
+
+**Date**: 2026-01-28
+**Type**: Technical Implementation Plan
+**Related**: [ADR-024: Feature Flagging Strategy](../adr/0024-feature-flagging-strategy.md), [ADR-007: Configuration and Secrets Management](../adr/0007-configuration-and-secrets-management.md)
+**Status**: Ready for Implementation
+
+---
+
+## Project Overview
+
+Implement a simple, configuration-based feature flag system that integrates with the existing Zod-validated configuration in `src/config/env.ts`. The system will support both backend and frontend feature flags through environment variables, with type-safe access patterns and helper utilities.
+
+### Key Success Criteria
+
+1. Feature flags accessible via type-safe API on both backend and frontend
+2. Zero runtime overhead when flag is disabled (compile-time elimination where possible)
+3. Consistent naming convention (environment variables and code access)
+4. Graceful degradation (missing flag defaults to disabled)
+5. Easy migration path to external service (Flagsmith/LaunchDarkly) in the future
+6. Full test coverage with mocking utilities
+
+### Estimated Total Effort
+
+| Phase                             | Estimate       |
+| --------------------------------- | -------------- |
+| Phase 1: Backend Infrastructure   | 3-5 hours      |
+| Phase 2: Frontend Infrastructure  | 2-3 hours      |
+| Phase 3: Documentation & Examples | 1-2 hours      |
+| **Total**                         | **6-10 hours** |
+
+---
+
+## Current State Analysis
+
+### Backend Configuration (`src/config/env.ts`)
+
+- Zod-based schema validation at startup
+- Organized into logical groups (database, redis, auth, smtp, ai, etc.)
+- Helper exports for service availability (`isSmtpConfigured`, `isAiConfigured`, etc.)
+- Environment helpers (`isProduction`, `isTest`, `isDevelopment`)
+- Fail-fast on invalid configuration
+
+### Frontend Configuration (`src/config.ts`)
+
+- Uses `import.meta.env` (Vite environment variables)
+- Organized into sections (app, google, sentry)
+- Boolean parsing for string env vars
+- Type declarations in `src/vite-env.d.ts`
+
+### Existing Patterns to Follow
+
+```typescript
+// Backend - service availability check pattern
+export const isSmtpConfigured =
+  !!config.smtp.host && !!config.smtp.user && !!config.smtp.pass;
+
+// Frontend - boolean parsing pattern
+enabled: import.meta.env.VITE_SENTRY_ENABLED !== 'false',
+```
+
+---
+
+## Task Breakdown
+
+### Phase 1: Backend Feature Flag Infrastructure
+
+#### [1.1] Define Feature Flag Schema in env.ts
+
+**Complexity**: Low
+**Estimate**: 30-45 minutes
+**Dependencies**: None
+**Parallelizable**: Yes
+
+**Description**: Add a new `featureFlags` section to the Zod schema in `src/config/env.ts`.
+
+**Acceptance Criteria**:
+
+- [ ] New `featureFlagsSchema` Zod object defined
+- [ ] Schema supports boolean flags with defaults to `false` (opt-in model)
+- [ ] Schema added to main `envSchema` object
+- [ ] Type exported as part of `EnvConfig`
+
+**Implementation Details**:
+
+```typescript
+// src/config/env.ts
+
+/**
+ * Feature flags configuration schema (ADR-024).
+ * All flags default to false (disabled) for safety.
+ * Set to 'true' in environment to enable.
+ */
+const featureFlagsSchema = z.object({
+  // Example flags - replace with actual feature flags as needed
+  newDashboard: booleanString(false),      // FEATURE_NEW_DASHBOARD
+  betaRecipes: booleanString(false),       // FEATURE_BETA_RECIPES
+  experimentalAi: booleanString(false),    // FEATURE_EXPERIMENTAL_AI
+  debugMode: booleanString(false),         // FEATURE_DEBUG_MODE
+});
+
+// In loadEnvVars():
+featureFlags: {
+  newDashboard: process.env.FEATURE_NEW_DASHBOARD,
+  betaRecipes: process.env.FEATURE_BETA_RECIPES,
+  experimentalAi: process.env.FEATURE_EXPERIMENTAL_AI,
+  debugMode: process.env.FEATURE_DEBUG_MODE,
+},
+```
+
+**Risks/Notes**:
+
+- Naming convention: `FEATURE_*` prefix for all feature flag env vars
+- Default to `false` ensures features are opt-in, preventing accidental exposure
+
+---
+
+#### [1.2] Create Feature Flag Service Module
+
+**Complexity**: Medium
+**Estimate**: 1-2 hours
+**Dependencies**: [1.1]
+**Parallelizable**: No (depends on 1.1)
+
+**Description**: Create a dedicated service module for feature flag access with helper functions.
+
+**File**: `src/services/featureFlags.server.ts`
+
+**Acceptance Criteria**:
+
+- [ ] `isFeatureEnabled(flagName)` function for checking flags
+- [ ] `getAllFeatureFlags()` function for debugging/admin endpoints
+- [ ] Type-safe flag name parameter (union type or enum)
+- [ ] Exported helper booleans for common flags (similar to `isSmtpConfigured`)
+- [ ] Logging when feature flag is checked in development mode
+
+**Implementation Details**:
+
+```typescript
+// src/services/featureFlags.server.ts
+import { config, isDevelopment } from '../config/env';
+import { logger } from './logger.server';
+
+export type FeatureFlagName = keyof typeof config.featureFlags;
+
+/**
+ * Check if a feature flag is enabled.
+ * @param flagName - The name of the feature flag to check
+ * @returns boolean indicating if the feature is enabled
+ */
+export function isFeatureEnabled(flagName: FeatureFlagName): boolean {
+  const enabled = config.featureFlags[flagName];
+
+  if (isDevelopment) {
+    logger.debug({ flag: flagName, enabled }, 'Feature flag checked');
+  }
+
+  return enabled;
+}
+
+/**
+ * Get all feature flags and their current states.
+ * Useful for debugging and admin endpoints.
+ */
+export function getAllFeatureFlags(): Record<FeatureFlagName, boolean> {
+  return { ...config.featureFlags };
+}
+
+// Convenience exports for common flag checks
+export const isNewDashboardEnabled = config.featureFlags.newDashboard;
+export const isBetaRecipesEnabled = config.featureFlags.betaRecipes;
+export const isExperimentalAiEnabled = config.featureFlags.experimentalAi;
+export const isDebugModeEnabled = config.featureFlags.debugMode;
+```
+
+**Risks/Notes**:
+
+- Keep logging minimal to avoid performance impact
+- Convenience exports are evaluated once at startup (not dynamic)
+
+---
+
+#### [1.3] Add Admin Endpoint for Feature Flag Status
+
+**Complexity**: Low
+**Estimate**: 30-45 minutes
+**Dependencies**: [1.2]
+**Parallelizable**: No (depends on 1.2)
+
+**Description**: Add an admin/health endpoint to view current feature flag states.
+
+**File**: `src/routes/admin.routes.ts` (or `stats.routes.ts` if admin routes don't exist)
+
+**Acceptance Criteria**:
+
+- [ ] `GET /api/v1/admin/feature-flags` endpoint (admin-only)
+- [ ] Returns JSON object with all flags and their states
+- [ ] Requires admin authentication
+- [ ] Endpoint documented in Swagger
+
+**Implementation Details**:
+
+```typescript
+// In appropriate routes file
+router.get('/feature-flags', requireAdmin, async (req, res) => {
+  const flags = getAllFeatureFlags();
+  sendSuccess(res, { flags });
+});
+```
+
+**Risks/Notes**:
+
+- Ensure endpoint is protected (admin-only)
+- Consider caching response if called frequently
+
+---
+
+#### [1.4] Backend Unit Tests
+
+**Complexity**: Medium
+**Estimate**: 1-2 hours
+**Dependencies**: [1.1], [1.2]
+**Parallelizable**: Yes (can start after 1.1, in parallel with 1.3)
+
+**Description**: Write unit tests for feature flag configuration and service.
+
+**Files**:
+
+- `src/config/env.test.ts` (add feature flag tests)
+- `src/services/featureFlags.server.test.ts` (new file)
+
+**Acceptance Criteria**:
+
+- [ ] Test default values (all false)
+- [ ] Test parsing 'true'/'false' strings
+- [ ] Test `isFeatureEnabled()` function
+- [ ] Test `getAllFeatureFlags()` function
+- [ ] Test type safety (TypeScript compile-time checks)
+
+**Implementation Details**:
+
+```typescript
+// src/config/env.test.ts - add to existing file
+describe('featureFlags configuration', () => {
+  it('should default all feature flags to false', async () => {
+    setValidEnv();
+    const { config } = await import('./env');
+
+    expect(config.featureFlags.newDashboard).toBe(false);
+    expect(config.featureFlags.betaRecipes).toBe(false);
+  });
+
+  it('should parse FEATURE_NEW_DASHBOARD as true when set', async () => {
+    setValidEnv({ FEATURE_NEW_DASHBOARD: 'true' });
+    const { config } = await import('./env');
+
+    expect(config.featureFlags.newDashboard).toBe(true);
+  });
+});
+
+// src/services/featureFlags.server.test.ts - new file
+describe('featureFlags service', () => {
+  describe('isFeatureEnabled', () => {
+    it('should return false for disabled flags', () => {
+      expect(isFeatureEnabled('newDashboard')).toBe(false);
+    });
+
+    // ... more tests
+  });
+});
+```
+
+---
+
+### Phase 2: Frontend Feature Flag Infrastructure
+
+#### [2.1] Add Frontend Feature Flag Config
+
+**Complexity**: Low
+**Estimate**: 30-45 minutes
+**Dependencies**: None (can run in parallel with Phase 1)
+**Parallelizable**: Yes
+
+**Description**: Add feature flags to the frontend config module.
+
+**Files**:
+
+- `src/config.ts` - Add featureFlags section
+- `src/vite-env.d.ts` - Add type declarations
+
+**Acceptance Criteria**:
+
+- [ ] Feature flags section added to `src/config.ts`
+- [ ] TypeScript declarations updated in `vite-env.d.ts`
+- [ ] Boolean parsing consistent with existing pattern
+- [ ] Default to false when env var not set
+
+**Implementation Details**:
+
+```typescript
+// src/config.ts
+const config = {
+  // ... existing sections ...
+
+  /**
+   * Feature flags for conditional feature rendering (ADR-024).
+   * All flags default to false (disabled) when not explicitly set.
+   */
+  featureFlags: {
+    newDashboard: import.meta.env.VITE_FEATURE_NEW_DASHBOARD === 'true',
+    betaRecipes: import.meta.env.VITE_FEATURE_BETA_RECIPES === 'true',
+    experimentalAi: import.meta.env.VITE_FEATURE_EXPERIMENTAL_AI === 'true',
+    debugMode: import.meta.env.VITE_FEATURE_DEBUG_MODE === 'true',
+  },
+};
+
+// src/vite-env.d.ts
+interface ImportMetaEnv {
+  // ... existing declarations ...
+  readonly VITE_FEATURE_NEW_DASHBOARD?: string;
+  readonly VITE_FEATURE_BETA_RECIPES?: string;
+  readonly VITE_FEATURE_EXPERIMENTAL_AI?: string;
+  readonly VITE_FEATURE_DEBUG_MODE?: string;
+}
+```
+
+---
+
+#### [2.2] Create useFeatureFlag React Hook
+
+**Complexity**: Medium
+**Estimate**: 1-1.5 hours
+**Dependencies**: [2.1]
+**Parallelizable**: No (depends on 2.1)
+
+**Description**: Create a React hook for checking feature flags in components.
+
+**File**: `src/hooks/useFeatureFlag.ts`
+
+**Acceptance Criteria**:
+
+- [ ] `useFeatureFlag(flagName)` hook returns boolean
+- [ ] Type-safe flag name parameter
+- [ ] Memoized to prevent unnecessary re-renders
+- [ ] Optional `FeatureFlag` component for conditional rendering
+
+**Implementation Details**:
+
+```typescript
+// src/hooks/useFeatureFlag.ts
+import { useMemo } from 'react';
+import config from '../config';
+
+export type FeatureFlagName = keyof typeof config.featureFlags;
+
+/**
+ * Hook to check if a feature flag is enabled.
+ *
+ * @param flagName - The name of the feature flag to check
+ * @returns boolean indicating if the feature is enabled
+ *
+ * @example
+ * const isNewDashboard = useFeatureFlag('newDashboard');
+ * if (isNewDashboard) {
+ *   return <NewDashboard />;
+ * }
+ */
+export function useFeatureFlag(flagName: FeatureFlagName): boolean {
+  return useMemo(() => config.featureFlags[flagName], [flagName]);
+}
+
+/**
+ * Get all feature flags (useful for debugging).
+ */
+export function useAllFeatureFlags(): Record<FeatureFlagName, boolean> {
+  return useMemo(() => ({ ...config.featureFlags }), []);
+}
+```
+
+---
+
+#### [2.3] Create FeatureFlag Component
+
+**Complexity**: Low
+**Estimate**: 30-45 minutes
+**Dependencies**: [2.2]
+**Parallelizable**: No (depends on 2.2)
+
+**Description**: Create a declarative component for feature flag conditional rendering.
+
+**File**: `src/components/FeatureFlag.tsx`
+
+**Acceptance Criteria**:
+
+- [ ] `<FeatureFlag name="flagName">` component
+- [ ] Children rendered only when flag is enabled
+- [ ] Optional `fallback` prop for disabled state
+- [ ] TypeScript-enforced flag names
+
+**Implementation Details**:
+
+```typescript
+// src/components/FeatureFlag.tsx
+import { ReactNode } from 'react';
+import { useFeatureFlag, FeatureFlagName } from '../hooks/useFeatureFlag';
+
+interface FeatureFlagProps {
+  /** The name of the feature flag to check */
+  name: FeatureFlagName;
+  /** Content to render when feature is enabled */
+  children: ReactNode;
+  /** Optional content to render when feature is disabled */
+  fallback?: ReactNode;
+}
+
+/**
+ * Conditionally renders children based on feature flag state.
+ *
+ * @example
+ * <FeatureFlag name="newDashboard" fallback={<OldDashboard />}>
+ *   <NewDashboard />
+ * </FeatureFlag>
+ */
+export function FeatureFlag({ name, children, fallback = null }: FeatureFlagProps) {
+  const isEnabled = useFeatureFlag(name);
+  return <>{isEnabled ? children : fallback}</>;
+}
+```
+
+---
+
+#### [2.4] Frontend Unit Tests
+
+**Complexity**: Medium
+**Estimate**: 1-1.5 hours
+**Dependencies**: [2.1], [2.2], [2.3]
+**Parallelizable**: No (depends on previous frontend tasks)
+
+**Description**: Write unit tests for frontend feature flag utilities.
+
+**Files**:
+
+- `src/config.test.ts` (add feature flag tests)
+- `src/hooks/useFeatureFlag.test.ts` (new file)
+- `src/components/FeatureFlag.test.tsx` (new file)
+
+**Acceptance Criteria**:
+
+- [ ] Test config structure includes featureFlags
+- [ ] Test default values (all false)
+- [ ] Test hook returns correct values
+- [ ] Test component renders/hides children correctly
+- [ ] Test fallback rendering
+
+**Implementation Details**:
+
+```typescript
+// src/hooks/useFeatureFlag.test.ts
+import { renderHook } from '@testing-library/react';
+import { useFeatureFlag, useAllFeatureFlags } from './useFeatureFlag';
+
+describe('useFeatureFlag', () => {
+  it('should return false for disabled flags', () => {
+    const { result } = renderHook(() => useFeatureFlag('newDashboard'));
+    expect(result.current).toBe(false);
+  });
+});
+
+// src/components/FeatureFlag.test.tsx
+import { render, screen } from '@testing-library/react';
+import { FeatureFlag } from './FeatureFlag';
+
+describe('FeatureFlag', () => {
+  it('should not render children when flag is disabled', () => {
+    render(
+      <FeatureFlag name="newDashboard">
+        <div data-testid="new-feature">New Feature</div>
+      </FeatureFlag>
+    );
+    expect(screen.queryByTestId('new-feature')).not.toBeInTheDocument();
+  });
+
+  it('should render fallback when flag is disabled', () => {
+    render(
+      <FeatureFlag name="newDashboard" fallback={<div>Old Feature</div>}>
+        <div>New Feature</div>
+      </FeatureFlag>
+    );
+    expect(screen.getByText('Old Feature')).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+### Phase 3: Documentation & Integration
+
+#### [3.1] Update ADR-024 with Implementation Status
+
+**Complexity**: Low
+**Estimate**: 30 minutes
+**Dependencies**: [1.1], [1.2], [2.1], [2.2]
+**Parallelizable**: Yes (can be done after core implementation)
+
+**Description**: Update ADR-024 to mark it as implemented and add implementation details.
+
+**File**: `docs/adr/0024-feature-flagging-strategy.md`
+
+**Acceptance Criteria**:
+
+- [ ] Status changed from "Proposed" to "Accepted"
+- [ ] Implementation status section added
+- [ ] Key files documented
+- [ ] Usage examples included
+
+---
+
+#### [3.2] Update Environment Documentation
+
+**Complexity**: Low
+**Estimate**: 30 minutes
+**Dependencies**: [1.1], [2.1]
+**Parallelizable**: Yes
+
+**Description**: Add feature flag environment variables to documentation.
+
+**Files**:
+
+- `docs/getting-started/ENVIRONMENT.md`
+- `.env.example`
+
+**Acceptance Criteria**:
+
+- [ ] Feature flag variables documented in ENVIRONMENT.md
+- [ ] New section "Feature Flags" added
+- [ ] `.env.example` updated with commented feature flag examples
+
+**Implementation Details**:
+
+```bash
+# .env.example addition
+# ===================
+# Feature Flags (ADR-024)
+# ===================
+# All feature flags default to disabled (false) when not set.
+# Set to 'true' to enable a feature.
+#
+# FEATURE_NEW_DASHBOARD=false
+# FEATURE_BETA_RECIPES=false
+# FEATURE_EXPERIMENTAL_AI=false
+# FEATURE_DEBUG_MODE=false
+#
+# Frontend equivalents (prefix with VITE_):
+# VITE_FEATURE_NEW_DASHBOARD=false
+# VITE_FEATURE_BETA_RECIPES=false
+```
+
+---
+
+#### [3.3] Create CODE-PATTERNS Entry
+
+**Complexity**: Low
+**Estimate**: 30 minutes
+**Dependencies**: All implementation tasks
+**Parallelizable**: Yes
+
+**Description**: Add feature flag usage patterns to CODE-PATTERNS.md.
+
+**File**: `docs/development/CODE-PATTERNS.md`
+
+**Acceptance Criteria**:
+
+- [ ] Feature flag section added with examples
+- [ ] Backend usage pattern documented
+- [ ] Frontend usage pattern documented
+- [ ] Testing pattern documented
+
+---
+
+#### [3.4] Update CLAUDE.md Quick Reference
+
+**Complexity**: Low
+**Estimate**: 15 minutes
+**Dependencies**: All implementation tasks
+**Parallelizable**: Yes
+
+**Description**: Add feature flags to the CLAUDE.md quick reference tables.
+
+**File**: `CLAUDE.md`
+
+**Acceptance Criteria**:
+
+- [ ] Feature flags added to "Key Patterns" table
+- [ ] Reference to featureFlags service added
+
+---
+
+## Implementation Sequence
+
+### Phase 1 (Backend) - Can Start Immediately
+
+```text
+[1.1] Schema ──────────┬──> [1.2] Service ──> [1.3] Admin Endpoint
+                       │
+                       └──> [1.4] Backend Tests (can start after 1.1)
+```
+
+### Phase 2 (Frontend) - Can Start Immediately (Parallel with Phase 1)
+
+```text
+[2.1] Config ──> [2.2] Hook ──> [2.3] Component ──> [2.4] Frontend Tests
+```
+
+### Phase 3 (Documentation) - After Implementation
+
+```text
+All Phase 1 & 2 Tasks ──> [3.1] ADR Update
+                     ├──> [3.2] Env Docs
+                     ├──> [3.3] Code Patterns
+                     └──> [3.4] CLAUDE.md
+```
+
+---
+
+## Critical Path
+
+The minimum path to a working feature flag system:
+
+1. **[1.1] Schema** (30 min) - Required for backend
+2. **[1.2] Service** (1.5 hr) - Required for backend access
+3. **[2.1] Frontend Config** (30 min) - Required for frontend
+4. **[2.2] Hook** (1 hr) - Required for React integration
+
+**Critical path duration**: ~3.5 hours
+
+Non-critical but recommended:
+
+- Admin endpoint (debugging)
+- FeatureFlag component (developer convenience)
+- Tests (quality assurance)
+- Documentation (maintainability)
+
+---
+
+## Scope Recommendations
+
+### MVP (Minimum Viable Implementation)
+
+Include in initial implementation:
+
+- [1.1] Backend schema with 2-3 example flags
+- [1.2] Feature flag service
+- [2.1] Frontend config
+- [2.2] useFeatureFlag hook
+- [1.4] Core backend tests
+- [2.4] Core frontend tests
+
+### Enhancements (Future Iterations)
+
+Defer to follow-up work:
+
+- Admin endpoint for flag visibility
+- FeatureFlag component (nice-to-have)
+- Dynamic flag updates without restart (requires external service)
+- User-specific flags (A/B testing)
+- Flag analytics/usage tracking
+- Gradual rollout percentages
+
+### Explicitly Out of Scope
+
+- Integration with Flagsmith/LaunchDarkly (future ADR)
+- Database-stored flags (requires schema changes)
+- Real-time flag updates (WebSocket/SSE)
+- Flag inheritance/hierarchy
+- Flag audit logging
+
+---
+
+## Testing Strategy
+
+### Backend Tests
+
+| Test Type         | Coverage Target                          | Location                                   |
+| ----------------- | ---------------------------------------- | ------------------------------------------ |
+| Schema validation | Parse true/false, defaults               | `src/config/env.test.ts`                   |
+| Service functions | `isFeatureEnabled`, `getAllFeatureFlags` | `src/services/featureFlags.server.test.ts` |
+| Integration       | Admin endpoint (if added)                | `src/routes/admin.routes.test.ts`          |
+
+### Frontend Tests
+
+| Test Type           | Coverage Target             | Location                              |
+| ------------------- | --------------------------- | ------------------------------------- |
+| Config structure    | featureFlags section exists | `src/config.test.ts`                  |
+| Hook behavior       | Returns correct values      | `src/hooks/useFeatureFlag.test.ts`    |
+| Component rendering | Conditional children        | `src/components/FeatureFlag.test.tsx` |
+
+### Mocking Pattern for Tests
+
+```typescript
+// Backend - reset modules to test different flag states
+beforeEach(() => {
+  vi.resetModules();
+  process.env.FEATURE_NEW_DASHBOARD = 'true';
+});
+
+// Frontend - mock config module
+vi.mock('../config', () => ({
+  default: {
+    featureFlags: {
+      newDashboard: true,
+      betaRecipes: false,
+    },
+  },
+}));
+```
+
+---
+
+## Risk Assessment
+
+| Risk                                        | Impact | Likelihood | Mitigation                                                    |
+| ------------------------------------------- | ------ | ---------- | ------------------------------------------------------------- |
+| Flag state inconsistency (backend/frontend) | Medium | Low        | Use same env var naming, document sync requirements           |
+| Performance impact from flag checks         | Low    | Low        | Flags cached at startup, no runtime DB calls                  |
+| Stale flags after deployment                | Medium | Medium     | Document restart requirement, consider future dynamic loading |
+| Feature creep (too many flags)              | Medium | Medium     | Require ADR for new flags, sunset policy                      |
+| Missing flag causes crash                   | High   | Low        | Default to false, graceful degradation                        |
+
+---
+
+## Files to Create
+
+| File                                       | Purpose                      |
+| ------------------------------------------ | ---------------------------- |
+| `src/services/featureFlags.server.ts`      | Backend feature flag service |
+| `src/services/featureFlags.server.test.ts` | Backend tests                |
+| `src/hooks/useFeatureFlag.ts`              | React hook for flag access   |
+| `src/hooks/useFeatureFlag.test.ts`         | Hook tests                   |
+| `src/components/FeatureFlag.tsx`           | Declarative flag component   |
+| `src/components/FeatureFlag.test.tsx`      | Component tests              |
+
+## Files to Modify
+
+| File                                         | Changes                            |
+| -------------------------------------------- | ---------------------------------- |
+| `src/config/env.ts`                          | Add featureFlagsSchema and loading |
+| `src/config/env.test.ts`                     | Add feature flag tests             |
+| `src/config.ts`                              | Add featureFlags section           |
+| `src/config.test.ts`                         | Add feature flag tests             |
+| `src/vite-env.d.ts`                          | Add VITE*FEATURE*\* declarations   |
+| `.env.example`                               | Add feature flag examples          |
+| `docs/adr/0024-feature-flagging-strategy.md` | Update status and details          |
+| `docs/getting-started/ENVIRONMENT.md`        | Document feature flag vars         |
+| `docs/development/CODE-PATTERNS.md`          | Add usage patterns                 |
+| `CLAUDE.md`                                  | Add to quick reference             |
+
+---
+
+## Verification Commands
+
+After implementation, run these commands in the dev container:
+
+```bash
+# Type checking
+podman exec -it flyer-crawler-dev npm run type-check
+
+# Backend unit tests
+podman exec -it flyer-crawler-dev npm run test:unit -- --grep "featureFlag"
+
+# Frontend tests (includes hook and component tests)
+podman exec -it flyer-crawler-dev npm run test:unit -- --grep "FeatureFlag"
+
+# Full test suite
+podman exec -it flyer-crawler-dev npm test
+```
+
+---
+
+## Example Usage (Post-Implementation)
+
+### Backend Route Handler
+
+```typescript
+// src/routes/flyers.routes.ts
+import { isFeatureEnabled } from '../services/featureFlags.server';
+
+router.get('/dashboard', async (req, res) => {
+  if (isFeatureEnabled('newDashboard')) {
+    // New dashboard logic
+    return sendSuccess(res, { version: 'v2', data: await getNewDashboardData() });
+  }
+  // Legacy dashboard
+  return sendSuccess(res, { version: 'v1', data: await getLegacyDashboardData() });
+});
+```
+
+### React Component
+
+```tsx
+// src/pages/Dashboard.tsx
+import { FeatureFlag } from '../components/FeatureFlag';
+import { useFeatureFlag } from '../hooks/useFeatureFlag';
+
+// Option 1: Declarative component
+function Dashboard() {
+  return (
+    <FeatureFlag name="newDashboard" fallback={<LegacyDashboard />}>
+      <NewDashboard />
+    </FeatureFlag>
+  );
+}
+
+// Option 2: Hook for logic
+function DashboardWithLogic() {
+  const isNewDashboard = useFeatureFlag('newDashboard');
+
+  useEffect(() => {
+    if (isNewDashboard) {
+      analytics.track('new_dashboard_viewed');
+    }
+  }, [isNewDashboard]);
+
+  return isNewDashboard ? <NewDashboard /> : <LegacyDashboard />;
+}
+```
+
+---
+
+## Implementation Notes
+
+### Naming Convention
+
+| Context          | Pattern                   | Example                            |
+| ---------------- | ------------------------- | ---------------------------------- |
+| Backend env var  | `FEATURE_SNAKE_CASE`      | `FEATURE_NEW_DASHBOARD`            |
+| Frontend env var | `VITE_FEATURE_SNAKE_CASE` | `VITE_FEATURE_NEW_DASHBOARD`       |
+| Config property  | `camelCase`               | `config.featureFlags.newDashboard` |
+| Type/Hook param  | `camelCase`               | `isFeatureEnabled('newDashboard')` |
+
+### Flag Lifecycle
+
+1. **Adding a flag**: Add to both schemas, set default to `false`, document
+2. **Enabling a flag**: Set env var to `'true'`, restart application
+3. **Removing a flag**: Remove conditional code first, then remove flag from schemas
+4. **Sunset policy**: Flags should be removed within 3 months of full rollout
+
+---
+
+Last updated: 2026-01-28