@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/patterns-standards/DARK_MODE_MODAL_VISIBILITY.md

@@ -0,0 +1,258 @@
+# Dark Mode Modal Visibility - CSS Variables vs Explicit Colors
+
+## The Problem
+
+Modal dialogs become unreadable in dark mode when using CSS custom properties (CSS variables) for both background and text colors. The modal content becomes dark-on-dark or invisible.
+
+### Error Symptoms
+
+- Modal appears but content is invisible or barely visible
+- Users can't read confirmation messages
+- Buttons are hard to see or click
+- No console errors - just visual failure
+
+### Why It Was Hard
+
+- The modal "works" - it opens and closes correctly
+- No JavaScript errors to debug
+- Easy to miss during development if you only test in light mode
+- CSS variables silently resolve to values that don't provide contrast
+- The fix seems counterintuitive (use explicit colors instead of theme-aware variables)
+
+### Impact
+
+- Users cannot complete critical actions (like confirming unenrollment)
+- UX frustration and confusion
+- Potential data integrity issues if users click blindly
+
+---
+
+## The Solution
+
+### Root Cause
+
+When a modal uses CSS variables like `--color-surface` and `--color-text`, both resolve to dark values in dark mode:
+
+```jsx
+// BAD - Both resolve to dark colors in dark mode
+<div style={{ backgroundColor: 'var(--color-surface, #ffffff)' }}>
+  <p style={{ color: 'var(--color-text-secondary, #6b7280)' }}>
+    Confirm action?
+  </p>
+</div>
+```
+
+In dark mode:
+- `--color-surface` might be `#1f2937` (dark gray)
+- `--color-text-secondary` might be `#9ca3af` (light gray)
+
+But if the modal doesn't properly inherit theme context, or CSS variables cascade incorrectly, you get dark-on-dark.
+
+### How to Fix
+
+**Use explicit Tailwind classes** for critical modals instead of CSS variables:
+
+```jsx
+// GOOD - Explicit white background, explicit dark text
+<div className="relative inline-block w-full max-w-md p-6 my-8 overflow-hidden text-left align-middle transition-all transform bg-white rounded-lg shadow-xl">
+  <h3 className="text-lg font-semibold mb-2 text-red-600">
+    Confirm Unenrollment
+  </h3>
+  <p className="mb-4 text-gray-700">
+    Are you sure you want to unenroll{' '}
+    <strong className="text-gray-900">{userName}</strong>{' '}
+    from <strong className="text-gray-900">{courseTitle}</strong>?
+  </p>
+  <p className="text-sm mb-6 text-red-600">
+    This will also delete their course progress.
+  </p>
+
+  <div className="flex justify-end gap-3">
+    <button className="px-4 py-2 rounded-lg text-sm font-medium bg-gray-100 text-gray-700 hover:bg-gray-200">
+      Cancel
+    </button>
+    <button className="px-4 py-2 rounded-lg text-sm font-medium text-white bg-red-600 hover:bg-red-700 disabled:opacity-50">
+      Confirm
+    </button>
+  </div>
+</div>
+```
+
+### Key Changes
+
+| Element | Bad (CSS Variables) | Good (Explicit) |
+|---------|---------------------|-----------------|
+| Modal background | `style={{ backgroundColor: 'var(--color-surface)' }}` | `className="bg-white"` |
+| Primary text | `style={{ color: 'var(--color-text)' }}` | `className="text-gray-900"` |
+| Secondary text | `style={{ color: 'var(--color-text-secondary)' }}` | `className="text-gray-700"` |
+| Danger text | `style={{ color: '#dc2626' }}` | `className="text-red-600"` |
+| Cancel button | `style={{ backgroundColor: 'var(--color-surface-secondary)' }}` | `className="bg-gray-100 text-gray-700"` |
+| Danger button | `style={{ backgroundColor: '#dc2626' }}` | `className="bg-red-600 text-white"` |
+
+### Backdrop Fix
+
+Also use explicit classes for the modal backdrop:
+
+```jsx
+// BAD
+<div
+  className="fixed inset-0 transition-opacity"
+  style={{ backgroundColor: 'rgba(0, 0, 0, 0.5)' }}
+/>
+
+// GOOD
+<div className="fixed inset-0 transition-opacity bg-black bg-opacity-50" />
+```
+
+---
+
+## When to Use Explicit Colors
+
+Use explicit Tailwind classes for:
+
+1. **Confirmation modals** - Critical user decisions
+2. **Error dialogs** - Must be readable
+3. **Overlays and popups** - Need guaranteed contrast
+4. **Toast notifications** - Brief, need immediate visibility
+
+Keep CSS variables for:
+
+1. **Main page layouts** - Should respect theme
+2. **Navigation** - Part of the theme experience
+3. **Card backgrounds** - Follow user preference
+4. **Form inputs** - Theme-aware is appropriate
+
+---
+
+## Testing the Fix
+
+### Before (Dark Mode)
+- Modal appears with dark background
+- Text is barely visible or invisible
+- User cannot read confirmation message
+
+### After (Dark Mode)
+- Modal has white background
+- Text is clearly visible (gray/black)
+- Danger messages in red are prominent
+- Buttons have clear hover states
+
+### Test Cases
+
+1. Open modal in light mode - verify readable
+2. Open modal in dark mode - verify readable
+3. Toggle theme while modal is open - should remain readable
+4. Test on different screen brightnesses
+
+---
+
+## Prevention
+
+### Code Review Checklist
+
+- [ ] Modal backgrounds use explicit `bg-white` or `bg-gray-900`
+- [ ] Text colors use explicit Tailwind classes
+- [ ] Buttons have visible text in both modes
+- [ ] Backdrop uses `bg-black bg-opacity-50`
+
+### Pattern to Follow
+
+```jsx
+// Standard modal pattern for guaranteed visibility
+const ConfirmationModal = ({ isOpen, onClose, onConfirm, title, message, confirmText }) => {
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 overflow-y-auto">
+      <div className="flex items-center justify-center min-h-screen px-4 text-center">
+        {/* Backdrop */}
+        <div
+          className="fixed inset-0 bg-black bg-opacity-50 transition-opacity"
+          onClick={onClose}
+        />
+
+        {/* Modal */}
+        <div className="relative bg-white rounded-lg shadow-xl max-w-md w-full p-6 text-left">
+          <h3 className="text-lg font-semibold text-gray-900 mb-4">
+            {title}
+          </h3>
+          <p className="text-gray-700 mb-6">
+            {message}
+          </p>
+          <div className="flex justify-end gap-3">
+            <button
+              onClick={onClose}
+              className="px-4 py-2 bg-gray-100 text-gray-700 rounded-lg hover:bg-gray-200"
+            >
+              Cancel
+            </button>
+            <button
+              onClick={onConfirm}
+              className="px-4 py-2 bg-red-600 text-white rounded-lg hover:bg-red-700"
+            >
+              {confirmText}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};
+```
+
+---
+
+## Related Patterns
+
+- Theme Context Implementation
+- CSS Variables for Theming
+- Tailwind Dark Mode Configuration
+- Accessible Color Contrast
+
+---
+
+## Common Mistakes to Avoid
+
+- ❌ **Using CSS variables in modals** - They can resolve unexpectedly in dark mode
+- ❌ **Mixing inline styles and Tailwind** - Hard to debug theme issues
+- ❌ **Testing only in light mode** - Always test both modes
+- ❌ **Forgetting backdrop contrast** - Dark backdrop on dark page = invisible modal
+
+---
+
+## Resources
+
+- [Tailwind CSS Colors](https://tailwindcss.com/docs/customizing-colors)
+- [WCAG Color Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
+- [Accessible Modal Patterns](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
+
+---
+
+## Time to Implement
+
+**5-10 minutes** - Simple find and replace of style props with Tailwind classes
+
+## Difficulty Level
+
+⭐⭐ (2/5) - Easy fix once you understand the pattern, but hard to diagnose initially
+
+---
+
+**Author Notes:**
+
+This issue appeared in an admin enrollment management page where the unenroll confirmation modal was unreadable in dark mode. The user could see the modal backdrop but couldn't read the confirmation message or identify the buttons.
+
+The key insight: **modals are often displayed outside the normal theme context**, so relying on CSS variables can break. Explicit colors guarantee visibility regardless of theme state.
+
+For dark-mode-aware modals that match the theme, use `dark:` variant classes:
+```jsx
+className="bg-white dark:bg-gray-800 text-gray-900 dark:text-white"
+```
+
+But for critical confirmation dialogs, explicit light colors are often preferred for their "alert" feel.
+
+---
+
+**Created:** 2026-01-26
+**Context:** MERN Community LMS - Admin Enrollment Management
+**Files Changed:** `client/src/pages/admin/Enrollments.jsx`

package/skills-library/patterns-standards/ERROR_RESILIENCE_IMPLEMENTATION.md

@@ -0,0 +1,375 @@
+# ERROR RESILIENCE IMPLEMENTATION - FINAL PRODUCTION ENHANCEMENT
+
+**Date:** October 20, 2025  
+**Status:** ✅ PRODUCTION READY WITH ERROR RESILIENCE  
+**File:** `CREATE_VIDEO_PROGRESS_TABLES.sql` (Final Enterprise-Grade Version)
+
+---
+
+## 🛡️ ERROR RESILIENCE PATTERN IMPLEMENTED
+
+### Problem This Solves
+
+**Scenario:** During peak usage, `lesson_progress` table experiences intermittent write delays or locks
+- ❌ Without error handling: Student's video_progress write FAILS, progress lost
+- ✅ With error handling: Student's video_progress SUCCEEDS, error logged silently
+
+**User Impact Without Error Resilience:**
+```
+Video playback paused... ERROR saving progress
+[Progress Lost] 45 seconds of watch time gone
+User loses motivation ❌
+```
+
+**User Impact With Error Resilience:**
+```
+Video playback continues smoothly ✅
+Progress saved (45 seconds recorded)
+Admin finds and fixes issue later (error logged)
+User experience seamless ✅
+```
+
+---
+
+## 🏗️ IMPLEMENTATION DETAILS
+
+### 1. Created trigger_error_log Table
+
+**Purpose:** Capture trigger errors without aborting the write
+
+**Schema:**
+```sql
+CREATE TABLE IF NOT EXISTS trigger_error_log (
+  id uuid NOT NULL DEFAULT gen_random_uuid(),
+  trigger_name text NOT NULL,                    -- Which trigger failed
+  error_message text,                            -- PostgreSQL error message
+  error_context jsonb,                           -- Contextual data (user_id, lesson_id, etc.)
+  logged_at timestamptz DEFAULT NOW(),           -- When error occurred
+  CONSTRAINT trigger_error_log_pkey PRIMARY KEY (id)
+);
+```
+
+**Index for Performance:**
+```sql
+CREATE INDEX IF NOT EXISTS idx_trigger_error_log_recent 
+  ON trigger_error_log(logged_at DESC);
+```
+
+**Key Features:**
+- Lightweight (minimal storage footprint)
+- JSONB context for debugging
+- Indexed by timestamp (find recent errors quickly)
+- No query impact (separate table)
+
+---
+
+### 2. Enhanced Trigger Function with Exception Handling
+
+**Before (No Error Handling):**
+```plpgsql
+IF v_is_completed AND NOT v_was_completed THEN
+  INSERT INTO lesson_progress (...)
+  VALUES (...)
+  ON CONFLICT ... DO UPDATE SET ...;
+END IF;
+```
+
+**After (With Error Resilience):**
+```plpgsql
+IF v_is_completed AND NOT v_was_completed THEN
+  BEGIN
+    INSERT INTO lesson_progress (...)
+    VALUES (...)
+    ON CONFLICT ... DO UPDATE SET ...;
+  EXCEPTION WHEN OTHERS THEN
+    -- Capture error without aborting
+    v_error_msg := SQLERRM;
+    v_error_context := jsonb_build_object(
+      'user_id', NEW.user_id::text,
+      'lesson_id', NEW.lesson_id::text,
+      'course_id', NEW.course_id::text,
+      'completion_percentage', new_completion_percentage,
+      'sqlstate', SQLSTATE
+    );
+    
+    -- Log non-fatally
+    INSERT INTO trigger_error_log (...)
+    VALUES (...);
+  END;
+END IF;
+```
+
+**Key Improvements:**
+- ✅ Wraps lesson_progress upsert in BEGIN...EXCEPTION
+- ✅ Captures `SQLERRM` (error message)
+- ✅ Captures `SQLSTATE` (error code)
+- ✅ Stores context (user_id, lesson_id, completion %)
+- ✅ Logs to error table (non-fatal)
+- ✅ Video_progress write continues successfully
+
+---
+
+## 📊 BEHAVIOR COMPARISON
+
+### Without Error Handling
+
+```
+UPDATE video_progress SET total_watch_time_ms = 45000
+
+Trigger executes:
+  ✅ Calculate completion percentage: 45%
+  ✅ Set is_completed = false
+  ❌ INSERT INTO lesson_progress FAILS (table locked)
+  ❌ ENTIRE TRIGGER FAILS
+  ❌ VIDEO_PROGRESS UPDATE ROLLED BACK
+  ❌ STUDENT PROGRESS LOST
+
+Result: Student sees error, progress gone ❌
+```
+
+### With Error Handling
+
+```
+UPDATE video_progress SET total_watch_time_ms = 45000
+
+Trigger executes:
+  ✅ Calculate completion percentage: 45%
+  ✅ Set is_completed = false
+  ❌ INSERT INTO lesson_progress FAILS (table locked)
+  ✅ EXCEPTION CAUGHT
+  ✅ Error logged to trigger_error_log
+  ✅ VIDEO_PROGRESS UPDATE SUCCEEDS
+  ✅ STUDENT PROGRESS SAVED
+
+Result: Progress saved, admin notified via error log ✅
+```
+
+---
+
+## 🔍 DEBUGGING & MONITORING
+
+### Query Recent Errors
+
+```sql
+-- Check if trigger had recent failures
+SELECT 
+  trigger_name,
+  COUNT(*) as error_count,
+  MAX(logged_at) as last_error,
+  error_context->>'user_id' as affected_user
+FROM trigger_error_log
+WHERE logged_at > NOW() - INTERVAL '1 hour'
+GROUP BY trigger_name, error_context->>'user_id'
+ORDER BY last_error DESC;
+```
+
+### View Error Details
+
+```sql
+-- See exactly what failed and why
+SELECT 
+  logged_at,
+  error_message,
+  error_context->>'user_id' as user_id,
+  error_context->>'lesson_id' as lesson_id,
+  error_context->>'completion_percentage' as completion_pct,
+  error_context->>'sqlstate' as error_code
+FROM trigger_error_log
+WHERE logged_at > NOW() - INTERVAL '24 hours'
+ORDER BY logged_at DESC;
+```
+
+### Monitor Error Frequency
+
+```sql
+-- Track error patterns over time
+SELECT 
+  DATE_TRUNC('minute', logged_at) as minute,
+  COUNT(*) as errors_in_minute
+FROM trigger_error_log
+WHERE logged_at > NOW() - INTERVAL '1 day'
+GROUP BY DATE_TRUNC('minute', logged_at)
+ORDER BY minute DESC;
+```
+
+---
+
+## 🚨 WHEN TO INVESTIGATE
+
+### Action Needed If:
+- **Error spike:** > 10 errors in 1 hour
+- **Specific user:** Same user seeing repeated failures
+- **Specific lesson:** High error rate for one lesson
+- **Specific error code:** Pattern of same SQL error
+
+### Example Investigation
+
+```
+ERROR LOG ALERT:
+- 50 errors in last 5 minutes
+- All from same lesson_id
+- All with SQLSTATE = '40P01' (serialization failure)
+
+ACTION:
+1. Check lesson_progress table for locks
+2. Review transactions in that time window
+3. Possibly increase max_connections or tune application retry logic
+4. Monitor for recurrence
+```
+
+---
+
+## 💾 DATA RETENTION POLICY
+
+### Keep Error Logs For:
+- ✅ 7 days: Real-time debugging (find active issues)
+- ✅ 30 days: Pattern analysis (weekly reports)
+- ✅ 90 days: Historical trends (long-term insights)
+
+### Archive Older Logs
+
+```sql
+-- Monthly cleanup (run via cron or scheduler)
+DELETE FROM trigger_error_log
+WHERE logged_at < NOW() - INTERVAL '90 days';
+```
+
+---
+
+## 🎯 RESILIENCE GUARANTEES
+
+### What This Guarantees
+
+| Guarantee | Before | After |
+|-----------|--------|-------|
+| **Video progress saved** | ❌ No (if lesson_progress fails) | ✅ Yes (always) |
+| **Error visibility** | ❌ No (silent failure) | ✅ Yes (logged) |
+| **User experience** | ❌ Error shown to user | ✅ Seamless, silent handling |
+| **Data recovery** | ❌ Progress lost | ✅ Can investigate & fix |
+| **Admin debugging** | ❌ No info | ✅ Full error context |
+
+### What This Does NOT Guarantee
+
+- ❌ Does NOT guarantee lesson_progress is always updated
+- ❌ Does NOT hide the underlying issue (must be fixed)
+- ❌ Does NOT prevent the error (must monitor and investigate)
+- ⚠️ Requires active monitoring to detect issues
+
+---
+
+## 🔧 DEPLOYMENT NOTES
+
+### Safe to Deploy
+- ✅ Fully backward compatible
+- ✅ No migration needed
+- ✅ Error log table is optional (self-contained)
+- ✅ Can be deployed any time
+
+### Performance Impact
+- ✅ Negligible when no errors (one extra IF condition)
+- ✅ Minimal when errors occur (log insert is fast)
+- ✅ No impact on normal video progress tracking
+
+### Assumptions
+- ✅ Assumes `lesson_progress` table exists
+- ✅ Assumes `trigger_error_log` can be created
+- ✅ Assumes sufficient privileges to create table
+
+---
+
+## 📈 SCALABILITY NOTES
+
+### When lesson_progress Becomes a Bottleneck
+
+**Current Approach (Synchronous):**
+```
+Video progress write → Trigger → lesson_progress update (sync) → Done
+Performance: ~1-5ms
+```
+
+**Future Approach (Asynchronous):**
+```
+Video progress write → Trigger → events table (fast) → Done
+Background job → lesson_progress updates (async)
+Performance: ~1-2ms (write), +100ms (async processing)
+```
+
+**When to Switch:**
+- ✅ Current approach fine for < 100 concurrent users
+- ⚠️ Monitor if > 500 concurrent users
+- ❌ Switch to async if > 1000 concurrent users OR avg write time > 10ms
+
+---
+
+## ✅ FINAL CHECKLIST: PRODUCTION READY
+
+- ✅ Error tracking table created
+- ✅ Error index for performance
+- ✅ Trigger wrapped in exception handler
+- ✅ Error context captured (user_id, lesson_id, completion %)
+- ✅ SQLERRM and SQLSTATE captured
+- ✅ Video progress write never aborted
+- ✅ Deterministic timestamps (v_now)
+- ✅ NULL-safe completion logic
+- ✅ ON CONFLICT with indexed lookup
+- ✅ RLS policies idempotent
+- ✅ Comprehensive comments
+- ✅ Debugging queries documented
+- ✅ Data retention policy documented
+- ✅ Scalability guidance included
+
+---
+
+## 🚀 DEPLOYMENT CHECKLIST
+
+Before executing in Supabase:
+
+- [ ] Review the complete CREATE_VIDEO_PROGRESS_TABLES.sql script
+- [ ] Verify all table names match your schema (video_progress, lesson_progress)
+- [ ] Confirm you have privileges to create tables and indexes
+- [ ] Backup existing data (if any)
+- [ ] Plan monitoring for trigger_error_log
+- [ ] Communicate to team about new error tracking
+
+**Execution Steps:**
+1. Copy entire `CREATE_VIDEO_PROGRESS_TABLES.sql`
+2. Open Supabase SQL Editor
+3. Paste and click Run
+4. Verify: "Query executed successfully"
+5. Run verification queries from VERIFY_VIDEO_PROGRESS_DATABASE.sql
+
+---
+
+## 📝 MONITORING AFTER DEPLOYMENT
+
+### Week 1: Baseline Monitoring
+```sql
+-- Daily check: Are errors occurring?
+SELECT COUNT(*) as total_errors FROM trigger_error_log;
+SELECT COUNT(*) as errors_today 
+FROM trigger_error_log 
+WHERE logged_at > NOW() - INTERVAL '1 day';
+```
+
+### Week 2-4: Pattern Analysis
+```sql
+-- Identify any recurring issues
+SELECT error_message, COUNT(*) as occurrences
+FROM trigger_error_log
+WHERE logged_at > NOW() - INTERVAL '7 days'
+GROUP BY error_message
+ORDER BY occurrences DESC;
+```
+
+### Ongoing: Production Monitoring
+- Monitor error rate (alert if > 5/min)
+- Track affected users
+- Monitor trigger execution time
+- Plan scale upgrades if needed
+
+---
+
+**Status:** ✅ ENTERPRISE PRODUCTION READY  
+**Quality:** Maximum resilience while maintaining performance  
+**Ready to Deploy:** YES 🚀
+