united-tattoo/docs/prd/epic-feature-flags-controlled-rollbacks.md

Feature Flags Framework for Controlled Rollbacks — Brownfield Enhancement

Version: 1.0
Date: 2025-09-18
Owner: Product Manager (John)
Related Docs:

• docs/prd/rollback-strategy.md
• docs/brownfield-architecture.md
• docs/brownfield-architecture-booking.md
• docs/brownfield-architecture-public.md
• docs/brownfield-architecture-tech.md

---

Epic Title Feature Flags Framework for Controlled Rollbacks — Brownfield Enhancement

Epic Goal Implement a centralized, minimal feature flag framework and wire it to key surfaces (Admin, Booking, Public) to enable safe, fast rollbacks and controlled exposure per the rollback strategy.

Epic Description

Existing System Context

• Current relevant functionality:
  • Next.js 14 App Router running on Cloudflare Pages/Workers via OpenNext.
  • Admin (/admin), Booking (/book), and Public (/ and /artists) surfaces with route handlers under /app/api.
  • No project-wide feature flags; rollbacks require full deployment revert.
• Technology stack:
  • Next.js 14, OpenNext Cloudflare adapter, Cloudflare D1/R2, NextAuth (JWT), Tailwind + shadcn/ui, Zod validations.
• Integration points:
  • Cloudflare env vars via wrangler.toml ([env.preview.vars]/[env.production.vars]).
  • UI components/pages under app/, route handlers under app/api/.
  • lib/env.ts for env validation; rollback procedures documented in docs/prd/rollback-strategy.md.

Enhancement Details

• What’s being added/changed:
  • Introduce a simple, typed flags module (lib/flags.ts) that reads boolean switches from environment variables.
  • Add first-class flags for Admin, Booking, and Public UX controls as defined in rollback-strategy.md.
  • Gate critical UI flows and API endpoints behind these flags with graceful fallbacks (e.g., disable Booking submit with friendly messaging).
• How it integrates:
  • Flags read from env (wrangler vars); server-side checks in route handlers and server components, client-side checks for UI affordances.
  • No architectural changes; minimal localized conditionals and guard rails.
• Success criteria:
  • Toggling a flag disables the associated feature safely without redeploy.
  • Disabled states present appropriate UX and non-2xx responses for APIs (e.g., 503 with JSON message) where appropriate.
  • No impact on unaffected features; default flag values replicate current behavior.

Stories

1. Feature Flags Library & Configuration

   • Implement lib/flags.ts with typed boolean flags:
     • ADMIN_ENABLED, ARTISTS_MODULE_ENABLED, UPLOADS_ADMIN_ENABLED
     • BOOKING_ENABLED, PUBLIC_APPOINTMENT_REQUESTS_ENABLED, REFERENCE_UPLOADS_PUBLIC_ENABLED, DEPOSITS_ENABLED
     • PUBLIC_DB_ARTISTS_ENABLED, ADVANCED_NAV_SCROLL_ANIMATIONS_ENABLED
     • STRICT_CI_GATES_ENABLED, ISR_CACHE_R2_ENABLED
   • Read values from process.env (wrangler vars) with safe defaults that preserve current behavior.
   • Document expected vars and defaults in README and docs/prd/rollback-strategy.md linkage.
   • Optional: Update lib/env.ts to include non-breaking optional validation for key flags (boolean parsing).

2. Wire Flags to Critical Surfaces (Admin/Booking/Public)

   • Admin:
     • Gate /admin shell with ADMIN_ENABLED; show friendly “Temporarily unavailable” if disabled.
     • Gate admin uploads endpoints with UPLOADS_ADMIN_ENABLED; return 503 JSON on POST/DELETE when disabled.
   • Booking:
     • Gate BookingForm submit path with BOOKING_ENABLED; disabled state shows user message and redirects to /contact.
     • If/when public booking endpoint exists, gate with PUBLIC_APPOINTMENT_REQUESTS_ENABLED.
   • Public:
     • Gate advanced scroll/parallax with ADVANCED_NAV_SCROLL_ANIMATIONS_ENABLED; ensure no JS errors when off.
   • Add smoke tests/checklist notes to verify disabled vs enabled behavior.

3. Operational Guidance & Verification

   • Add a “Feature Flags Operations” section to docs/prd/rollback-strategy.md or a short ops note with:
     • How to toggle flags (wrangler vars / dashboard).
     • Expected UX/API behavior per flag.
     • Post-toggle smoke steps.
   • Ensure flags are listed in wrangler.toml example vars for preview/production (documentation only; no secrets committed).

Compatibility Requirements

• Existing APIs remain unchanged unless disabled via flags (return 503 with structured message when gated).
• No DB schema changes introduced.
• UI changes follow existing patterns and provide accessible fallback messages.
• Performance impact minimal (light conditional checks, no heavy client logic).
• Default state preserves current behavior if flags are unset.

Risk Mitigation

• Primary Risk: Misconfiguration of env vars causing unintended disablement.
• Mitigation: Safe defaults that preserve current behavior; add console.warn on server when a critical flag is undefined (non-fatal).
• Rollback Plan: Set flags to disable problematic surfaces immediately; revert local changes by removing guards if needed (code rollback not required in normal operation).

Definition of Done

• lib/flags.ts implemented with typed flags and safe defaults.
• Admin, Booking, Public surfaces gated with appropriate UX/API responses.
• Documentation updated (flags list, how to toggle, expected behaviors).
• Smoke verification steps executed for both enabled and disabled states.
• No regressions observed in unaffected areas.

Validation Checklist

Scope Validation

• Epic can be completed in 1–3 stories maximum.
• No architectural documentation required beyond existing brownfield references.
• Enhancement follows existing patterns (env-based configuration, conditional rendering).
• Integration complexity is manageable.

Risk Assessment

• Risk to existing system is low (additive, defensive controls).
• Rollback plan is feasible (toggle flags via env).
• Testing approach covers existing functionality (smoke on disabled/enabled).
• Team has sufficient knowledge of integration points.

Completeness Check

• Epic goal is clear and achievable.
• Stories are properly scoped (library, wiring, ops).
• Success criteria are measurable (toggle effects, UX/API responses).
• Dependencies identified (wrangler vars, docs updates).

Handoff to Story Manager Please develop detailed user stories for this brownfield epic. Key considerations:

• This is an enhancement to an existing system running Next.js 14 App Router on Cloudflare Pages/Workers with D1/R2 and OpenNext.
• Integration points:
  • Env vars from wrangler.toml ([env.preview.vars]/[env.production.vars]).
  • Admin pages under /app/admin, Booking under /app/book, related route handlers under /app/api.
  • Documented rollback procedures in docs/prd/rollback-strategy.md.
• Existing patterns to follow:
  • Zod validations for route handlers, shadcn/ui for UX, middleware RBAC, minimal conditional checks.
• Critical compatibility requirements:
  • Defaults preserve current behavior.
  • Disabled states provide clear user messaging and appropriate HTTP statuses for APIs (503).
  • No DB schema changes; no secrets in repo.
• Each story must include verification that existing functionality remains intact with flags both enabled and disabled.

Epic should maintain system integrity while enabling safe, immediate disablement of high-risk surfaces without a redeploy.