Feature Flags Architecture & Unleash Specification

This document is the authoritative engineering specification for feature flag management, progressive release rings, A/B experimentation, and emergency kill switches across the Debelu platform. Grounded directly in [packages/core/src/services/featureFlags.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/packages/core/src/services/featureFlags.ts), [FeatureFlagsContext.tsx](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/packages/core/src/contexts/FeatureFlagsContext.tsx), and the root unleash-proxy-client dependency, this specification details flag topologies, type-safe evaluations, and release lifecycles.

---

1. System Overview & Architecture

Debelu integrates an enterprise feature flagging system powered by Unleash (Edge Proxy + Frontend Client). Feature flags decouple code deployments from feature releases, enabling targeted canary rollouts by university campus, risk-free trunk-based development, and instantaneous circuit-breaker kill switches.

graph TD
    UnleashServer[Unleash Management Server / Edge Proxy] -->|Server-Sent Events SSE| ClientSDK[unleash-proxy-client]
    
    subgraph FrontendAppLayer [React 19 Frontend Layer]
        ClientSDK --> FFService[FeatureFlagsService Singleton]
        FFService --> Provider[FeatureFlagsProvider Context]
        Provider --> useFeatureFlag[useFeatureFlag Hook]
        useFeatureFlag --> UIComponent[Conditional React Component]
    end

    subgraph FallbackEngine [Offline & Local Fallback]
        LocalDefaults[Static Fallback Flags Dictionary] -.->|Fallback When Proxy Down| FFService
    end

1.1 Core Invariants

1. Type-Safe Flag Keys: All flag keys are enforced through the FlagKey union type; string literals are forbidden.
2. Deterministic Offline Fallbacks: If the Unleash Proxy server is unreachable, the client silently falls back to static default states without throwing errors or blocking rendering.
3. Zero Flash of Unstyled Content (FOUC): Flags initialize synchronously from memory cache, preventing visual layout jumping during React hydration.

---

2. Active Feature Flags Inventory

The table below catalogs all registered feature flags defined in FlagKey:

Flag Key (FlagKey)	Type	Default (Fallback)	Target Scope	Business & Operational Description
new_checkout_flow	Boolean	false	Buyer	Multi-step checkout UI with inline address validation and instant bank transfer.
nduzi_ai_assistant	Boolean	true	All Members	Controls visibility of the floating Nduzi Gemini AI chat assistant.
vendor_analytics_v2	Boolean	false	Vendors	Advanced conversion rate charts, traffic attribution, and sales funnel analytics.
buyer_chat_translation	Boolean	false	Chat	Real-time multi-dialect translation for campus buyer-to-vendor direct messages.
wallet_virtual_account	Boolean	true	Checkout	Dedicated NUBAN virtual bank account generation via Paystack DVA.
flash_sales_v2	Boolean	false	Buyer / Store	Real-time countdown timer banners and inventory progress bars for campus flash sales.
dispute_resolution_ui	Boolean	true	Support	Dedicated self-service escrow dispute and evidence submission interface.
dark_mode_forced	Boolean	false	UI	Forces system dark mode theme override across storefront views.
beta_vendor_marketing_tools	Boolean	false	Beta Vendors	Coupon code generator, broadcast SMS notifications, and social promo banners.
pwa_install_prompt	Boolean	true	Mobile Web	Custom prompt banner encouraging students to install the PWA to their home screen.
new_product_detail_modal	Boolean	true	Storefront	High-performance modal overlay for product details preserving list scroll state.
vendor_payout_schedule	Boolean	false	Vendors	Allows vendors to configure automated daily, weekly, or manual escrow payout withdrawals.
admin_audit_log_v2	Boolean	true	Staff (Admin)	High-performance chunked audit export viewer with filterable actor search.
maintenance_mode	Kill Switch	false	Platform	Redirects all storefront traffic to MaintenanceScreen; locks database mutations.
emergency_kill_switch	Kill Switch	false	Payments	Instantly disables Paystack checkout and payout transfer dispatching during active attacks.

---

3. Implementation & Usage Patterns

3.1 React Hook Consumption (useFeatureFlag)

import { useFeatureFlag } from '@debelu/core';
import { NewCheckoutExperience } from '@/components/checkout/NewCheckoutExperience';
import { LegacyCheckoutExperience } from '@/components/checkout/LegacyCheckoutExperience';

export function CheckoutContainer() {
  const { isEnabled, isLoading } = useFeatureFlag('new_checkout_flow');

  if (isLoading) return <CheckoutSkeleton />;
  return isEnabled ? <NewCheckoutExperience /> : <LegacyCheckoutExperience />;
}

3.2 Contextual Campus Targeting (Gradual Rollout)

Flags can evaluate custom user context attributes (e.g., student campus, vendor tier, or user ID):

// Context passed to Unleash Proxy
unleashClient.updateContext({
  userId: user.id,
  properties: {
    campus: 'UNILAG',
    role: 'vendor',
    appVersion: '1.0.4'
  }
});

This enables rolling out high-risk features to a single campus (e.g., UNILAG) before global deployment to UNN, UI, and OAU.

---

4. Emergency Kill Switches & Platform Controls

Kill switches are high-priority toggles designed to protect platform security and financial integrity:

sequenceDiagram
    autonumber
    participant Ops as Incident Commander / SRE
    participant Unleash as Unleash Dashboard
    participant Apps as Storefront & Backend Clusters

    Ops->>Unleash: Toggles emergency_kill_switch to ON
    Unleash-->>Apps: Pushes SSE event to all connected instances (< 500ms)
    Apps->>Apps: Disables Checkout Intent Ingest
    Apps-->>Ops: Instantaneous mitigation; payment flow suspended

1. maintenance_mode: Triggers full-screen maintenance screens across web and mobile clients, terminating non-staff sessions while preserving health check probes.
2. emergency_kill_switch: Freezes all outward bank transfer dispatches and pauses checkout payment intent creation if an upstream payment gateway or banking switch experiences catastrophic settlement errors.

---

5. Feature Flag Lifecycle Management

To prevent technical debt and codebase bloat, feature flags follow a mandatory 4-stage lifecycle:

stateDiagram-v2
    [*] --> Development: 1. Flag Created in FlagKey
    Development --> CanaryRollout: 2. PR Merged (Default: false)
    CanaryRollout --> FullRelease: 3. Targeted Campus Rollout (5% -> 25% -> 100%)
    FullRelease --> Retired: 4. Code Cleanup (Dead code removed)
    Retired --> [*]

1. Creation: Define the typed key in FlagKey with safe default fallback (false).
2. Canary Rollout: Target internal staff and beta vendor cohorts via Unleash user ID strategies.
3. Full Release: Gradually ramp traffic percentage ($10% \rightarrow 50% \rightarrow 100%$) while monitoring Sentry error budgets and checkout completion rates.
4. Graduation & Retirement (Mandatory within 30 days of 100% rollout): Remove the conditional flag check and legacy fallback code from the repository in a dedicated cleanup PR.

---

6. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal Release Engineer	Complete enterprise feature flags reference covering Unleash integration, typed FlagKey catalog, campus targeting, kill switches, and lifecycle retirement rules.	Active Living Standard