134 lines
7.2 KiB
Markdown
134 lines
7.2 KiB
Markdown
# 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
|
||
- [x] Existing APIs remain unchanged unless disabled via flags (return 503 with structured message when gated).
|
||
- [x] No DB schema changes introduced.
|
||
- [x] UI changes follow existing patterns and provide accessible fallback messages.
|
||
- [x] Performance impact minimal (light conditional checks, no heavy client logic).
|
||
- [x] 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
|
||
- [x] Epic can be completed in 1–3 stories maximum.
|
||
- [x] No architectural documentation required beyond existing brownfield references.
|
||
- [x] Enhancement follows existing patterns (env-based configuration, conditional rendering).
|
||
- [x] Integration complexity is manageable.
|
||
|
||
Risk Assessment
|
||
- [x] Risk to existing system is low (additive, defensive controls).
|
||
- [x] Rollback plan is feasible (toggle flags via env).
|
||
- [x] Testing approach covers existing functionality (smoke on disabled/enabled).
|
||
- [x] Team has sufficient knowledge of integration points.
|
||
|
||
Completeness Check
|
||
- [x] Epic goal is clear and achievable.
|
||
- [x] Stories are properly scoped (library, wiring, ops).
|
||
- [x] Success criteria are measurable (toggle effects, UX/API responses).
|
||
- [x] 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.
|