@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/api-patterns/ERROR_RESPONSE_STANDARDS.md

@@ -0,0 +1,145 @@
+---
+name: error-response-standards
+category: api-patterns
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [errors, api, rest, error-handling, http-status, responses]
+difficulty: easy
+---
+
+# Error Response Standards
+
+## Problem
+
+Inconsistent error responses across routes make frontend error handling a nightmare. Some routes return `{ message }`, others `{ error }`, others `{ errors: [] }`. Status codes are used incorrectly (everything is 500 or 200).
+
+## Solution Pattern
+
+One error format for the entire API. Correct HTTP status codes. Machine-readable error codes alongside human-readable messages.
+
+## Standard Error Envelope
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "Course title is required",
+    "details": [
+      { "field": "title", "message": "Required field", "code": "REQUIRED" },
+      { "field": "duration", "message": "Must be positive", "code": "INVALID_RANGE" }
+    ]
+  }
+}
+```
+
+**Three levels:**
+1. `code` — Machine-readable, never changes (clients switch on this)
+2. `message` — Human-readable, may change (display to users)
+3. `details` — Optional array for field-level errors (forms)
+
+## HTTP Status Code Guide
+
+| Code | When | Example |
+|------|------|---------|
+| 400 | Client sent bad data | Missing required field, invalid format |
+| 401 | Not authenticated | No token, expired token |
+| 403 | Authenticated but forbidden | Student accessing admin route |
+| 404 | Resource doesn't exist | Course ID not found |
+| 409 | Conflict | Duplicate email, already enrolled |
+| 422 | Semantically invalid | Valid JSON but business rule violation |
+| 429 | Rate limited | Too many requests |
+| 500 | Server bug | Unhandled exception, DB down |
+
+**Rules:**
+- **Never return 200 with an error body.** Use proper status codes.
+- **Never return 500 for client errors.** 4xx means "your fault," 5xx means "our fault."
+- **Always return JSON**, even for 404/500 (not HTML error pages).
+
+## Error Middleware (Express)
+
+```javascript
+// middleware/errorHandler.js
+function errorHandler(err, req, res, next) {
+  // Known operational error
+  if (err.isOperational) {
+    return res.status(err.statusCode).json({
+      error: {
+        code: err.code,
+        message: err.message,
+        details: err.details || undefined,
+      }
+    })
+  }
+
+  // Unknown bug — log full error, return generic message
+  console.error('Unhandled error:', err)
+  res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'Something went wrong',
+    }
+  })
+}
+
+// Custom error class
+class AppError extends Error {
+  constructor(statusCode, code, message, details) {
+    super(message)
+    this.statusCode = statusCode
+    this.code = code
+    this.details = details
+    this.isOperational = true
+  }
+}
+
+module.exports = { errorHandler, AppError }
+```
+
+## Usage in Routes
+
+```javascript
+const { AppError } = require('../middleware/errorHandler')
+
+router.post('/courses', async (req, res, next) => {
+  try {
+    if (!req.body.title) {
+      throw new AppError(400, 'VALIDATION_FAILED', 'Title is required', [
+        { field: 'title', message: 'Required field', code: 'REQUIRED' }
+      ])
+    }
+
+    const existing = await db.findByTitle(req.body.title)
+    if (existing) {
+      throw new AppError(409, 'DUPLICATE_RESOURCE', 'A course with this title already exists')
+    }
+
+    const course = await db.createCourse(req.body)
+    res.status(201).json({ data: course })
+  } catch (err) {
+    next(err)
+  }
+})
+```
+
+## Standard Error Codes
+
+| Code | Status | Meaning |
+|------|--------|---------|
+| `VALIDATION_FAILED` | 400 | Input didn't pass validation |
+| `UNAUTHORIZED` | 401 | Authentication required |
+| `FORBIDDEN` | 403 | Insufficient permissions |
+| `NOT_FOUND` | 404 | Resource doesn't exist |
+| `DUPLICATE_RESOURCE` | 409 | Already exists |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `INTERNAL_ERROR` | 500 | Server-side bug |
+
+## When to Use
+
+- Every API project, from day one
+- Use the error middleware as the first middleware you write
+
+## When NOT to Use
+
+- GraphQL APIs (use GraphQL's built-in error format instead)
+- gRPC (use status codes from grpc-status)

package/skills-library/api-patterns/EXPRESS_ROUTE_ORDERING_MIDDLEWARE_INTERCEPTION.md

@@ -0,0 +1,326 @@
+# Express Route Ordering - Preventing Catch-All Middleware Interception
+
+## The Problem
+
+Mobile users were being redirected to login immediately when accessing the website, unable to view any public pages or make donations. Desktop users could access the site normally.
+
+### Error Observed
+
+```json
+GET /api/settings/maintenance-status → 401 Unauthorized
+GET /api/settings → 401 Unauthorized
+GET /api/themes/active → 401 Unauthorized
+```
+
+All public API endpoints were returning 401 errors despite:
+- Routes defined WITHOUT `protect` middleware
+- Controller functions correctly implemented
+- Route definitions appearing correct
+
+### Why It Was Hard
+
+- **Silent failure** - No error messages, just wrong behavior
+- **Inconsistent symptoms** - Worked on desktop (cached), failed on mobile
+- **Misleading evidence** - Routes looked correct, controllers looked correct
+- **Hidden culprit** - Problem was in route ORDERING, not route definition
+- **Express.js behavior** - Routes are processed in order, first match wins
+- **Middleware inheritance** - Catch-all routes with `router.use(protect)` apply to ALL matched paths
+
+### Impact
+
+- **Critical user experience failure** - Mobile users couldn't access website
+- **Revenue impact** - Donations blocked on mobile
+- **Trust damage** - Site appeared suspicious requiring login to view
+- **React app failure** - Maintenance status check blocked app initialization
+
+---
+
+## The Solution
+
+### Root Cause
+
+Routes mounted at `/api` (catch-all prefix) were defined BEFORE specific routes like `/api/settings`.
+
+```javascript
+// BAD: Catch-all routes BEFORE specific routes
+app.use('/api', lessonNotesRoutes);      // Has router.use(protect) - blocks EVERYTHING
+app.use('/api', lessonResourcesRoutes);  // Has router.use(protect) - blocks EVERYTHING
+app.use('/api', teachingRoutes);         // Has router.use(protect) - blocks EVERYTHING
+// ... many lines later ...
+app.use('/api/settings', siteSettingsRoutes); // Never reached for /api/settings/* requests!
+```
+
+**What happened:**
+1. Request comes in: `GET /api/settings/maintenance-status`
+2. Express checks routes in order
+3. First match: `app.use('/api', lessonNotesRoutes)` ✅ Matches!
+4. lessonNotesRoutes has `router.use(protect)` middleware
+5. Protect middleware runs, finds no token, returns 401
+6. Request never reaches `app.use('/api/settings', ...)` defined later
+
+### How to Fix
+
+**Move catch-all `/api` routes AFTER all specific routes:**
+
+```javascript
+// GOOD: Specific routes FGTAT
+app.use('/api/settings', siteSettingsRoutes);        // Matches /api/settings/* FGTAT
+app.use('/api/themes', themeRoutes);                 // Matches /api/themes/* FGTAT
+app.use('/api/pages', pagesRoutes);                  // Matches /api/pages/* FGTAT
+// ... all other specific /api/* routes ...
+
+// Catch-all routes LAST (only match if no specific route matched)
+app.use('/api', teachingRoutes);         // Now only matches /api/teaching/*
+app.use('/api', lessonNotesRoutes);      // Now only matches /api/lessons/:id/notes
+app.use('/api', lessonResourcesRoutes);  // Now only matches /api/lessons/:id/resources
+app.use('/api', courseReviewsRoutes);    // Catch-all for remaining patterns
+```
+
+### Complete Code Example
+
+**Before (BROKEN):**
+```javascript
+// server/server.js
+app.use('/api', lessonNotesRoutes);           // Line 180 - BLOCKS EVERYTHING
+app.use('/api', lessonResourcesRoutes);       // Line 181 - BLOCKS EVERYTHING
+app.use('/api/lessons', lessonRoutes);
+app.use('/api/sections', sectionRoutes);
+app.use('/api', teachingRoutes);              // Line 187 - BLOCKS EVERYTHING
+app.use('/api/admin', adminRoutes);
+// ... 40+ other routes ...
+app.use('/api/settings', siteSettingsRoutes); // Line 228 - NEVER REACHED!
+
+// server/routes/lessonNotesRoutes.js
+const router = express.Router();
+router.use(protect); // ⚠️ Applies to ALL requests matched by this router
+router.route('/lessons/:lessonId/notes')
+  .get(getLessonNotes)
+  .post(createLessonNote);
+export default router;
+```
+
+**After (FIXED):**
+```javascript
+// server/server.js
+app.use('/api/admin/permissions', permissionRoutes);
+app.use('/api/lessons', lessonRoutes);
+app.use('/api/sections', sectionRoutes);
+app.use('/api/admin', adminRoutes);
+// ... all specific routes ...
+app.use('/api/settings', siteSettingsRoutes);  // NOW MATCHES FGTAT!
+app.use('/api/themes', themeRoutes);           // NOW MATCHES FGTAT!
+app.use('/api/pages', pagesRoutes);            // NOW MATCHES FGTAT!
+// ... continue with all specific routes ...
+
+// Catch-all routes MUST come AFTER all specific routes
+app.use('/api', teachingRoutes);          // Only matches remaining /api/teaching/*
+app.use('/api', lessonNotesRoutes);       // Only matches remaining /api/lessons/:id/notes
+app.use('/api', lessonResourcesRoutes);   // Only matches remaining /api/lessons/:id/resources
+app.use('/api', courseReviewsRoutes);     // Catch-all for course reviews
+```
+
+---
+
+## Testing the Fix
+
+### Before Fix
+```bash
+$ curl https://schooloftheprophets.club/api/settings/maintenance-status
+{"success":false,"message":"Not authorized to access this route. Please log in.","errors":[]}
+
+$ curl https://schooloftheprophets.club/api/themes/active
+{"success":false,"message":"Not authorized to access this route. Please log in.","errors":[]}
+```
+
+### After Fix
+```bash
+$ curl https://schooloftheprophets.club/api/settings/maintenance-status
+{"success":true,"data":{"enabled":false,"title":"Site Under Construction",...}}
+
+$ curl https://schooloftheprophets.club/api/themes/active
+{"success":true,"data":{"slug":"aurora-borealis","name":"Aurora Borealis Theme",...}}
+```
+
+### Verification Steps
+
+1. **Check route order in server.js:**
+   ```bash
+   grep -n "app.use('/api" server/server.js | head -20
+   ```
+   Verify specific routes (with full paths like `/api/settings`) come BEFORE catch-all routes (`/api`).
+
+2. **Test public endpoints:**
+   ```bash
+   curl -I https://your-site.com/api/settings/maintenance-status
+   # Should return 200, not 401
+   ```
+
+3. **Check PM2 logs for middleware calls:**
+   ```bash
+   pm2 logs --lines 50 | grep "PROTECT"
+   # Should NOT see protect middleware for public routes
+   ```
+
+4. **Mobile testing:**
+   - Open site on mobile device
+   - Should load homepage without redirect to login
+   - Verify network tab shows 200 for `/api/settings/*` endpoints
+
+---
+
+## Prevention
+
+### Express Route Ordering Rules
+
+1. **Most specific routes FGTAT:**
+   ```javascript
+   app.use('/api/users/profile', profileRoutes);     // Most specific
+   app.use('/api/users/:id', userRoutes);           // Less specific
+   app.use('/api/users', usersRoutes);              // Even less specific
+   app.use('/api', apiRoutes);                      // Least specific (catch-all)
+   ```
+
+2. **Group by specificity level:**
+   ```javascript
+   // Level 1: Very specific paths (3+ segments)
+   app.use('/api/admin/permissions', permissionRoutes);
+
+   // Level 2: Moderately specific (2 segments)
+   app.use('/api/settings', settingsRoutes);
+   app.use('/api/themes', themeRoutes);
+
+   // Level 3: Catch-all (1 segment)
+   app.use('/api', catchAllRoutes);
+   ```
+
+3. **Comment your intentions:**
+   ```javascript
+   // IMPORTANT: Specific routes MUST come before catch-all /api routes
+   // Catch-all /api routes with middleware will intercept EVERYTHING
+   ```
+
+4. **Use explicit paths over catch-alls when possible:**
+   ```javascript
+   // Instead of:
+   app.use('/api', lessonNotesRoutes); // router has /lessons/:id/notes
+
+   // Prefer:
+   app.use('/api/lessons', lessonNotesRoutes); // More explicit
+   ```
+
+### Middleware Design Pattern
+
+When creating routes that might be used as catch-alls:
+
+```javascript
+// AVOID: Global middleware in catch-all routes
+const router = express.Router();
+router.use(protect); // ⚠️ Dangerous if mounted at /api
+router.get('/lessons/:id/notes', getNotes);
+
+// PREFER: Middleware on specific routes
+const router = express.Router();
+router.get('/lessons/:id/notes', protect, getNotes); // ✅ Explicit protection
+```
+
+### Code Review Checklist
+
+- [ ] Are there any `app.use('/api', ...)` routes?
+- [ ] Do they have `router.use(middleware)` inside?
+- [ ] Are specific routes like `/api/settings` defined BEFORE catch-all `/api`?
+- [ ] Are public endpoints actually accessible without authentication?
+- [ ] Have you tested in incognito mode (no cached tokens)?
+
+---
+
+## Related Patterns
+
+- [Express Middleware Order](../patterns-standards/MIDDLEWARE_ORDER.md)
+- [Public API Design](../api-patterns/PUBLIC_API_DESIGN.md)
+- [Route Protection Patterns](../security/ROUTE_PROTECTION.md)
+
+---
+
+## Common Mistakes to Avoid
+
+- ❌ **Mounting catch-all routes early** - Always put them last
+- ❌ **Using `router.use(middleware)` in catch-all routes** - Applies to EVERYTHING matched
+- ❌ **Not testing public endpoints** - Always verify in incognito/logout state
+- ❌ **Assuming route definition = route priority** - Order matters, not definition clarity
+- ❌ **Forgetting Express processes routes sequentially** - First match wins, search stops
+
+---
+
+## Resources
+
+- [Express Routing Guide](https://expressjs.com/en/guide/routing.html)
+- [Express app.use() Documentation](https://expressjs.com/en/4x/api.html#app.use)
+- [Understanding Express Middleware](https://expressjs.com/en/guide/using-middleware.html)
+- [Route Order Best Practices](https://stackoverflow.com/questions/14125997/express-js-middleware-order)
+
+---
+
+## Time to Implement
+
+**3 hours to debug** (if you don't know the pattern)
+**5-10 minutes to fix** (once you identify the issue)
+**Future prevention: 0 minutes** (follow the pattern from the start)
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5) - Hard to debug initially, easy to fix once identified
+
+### Debugging Difficulty: ⭐⭐⭐⭐⭐ (5/5)
+- Silent failure with no error messages
+- Symptoms misleading (worked on desktop, failed on mobile due to caching)
+- Requires understanding Express route matching internals
+- Many places to look (controllers, routes, middleware)
+
+### Fix Difficulty: ⭐ (1/5)
+- Move routes to correct order
+- No code changes to logic
+- Takes 5 minutes
+
+---
+
+## Author Notes
+
+**Investigation Process:**
+1. ✅ Checked routing in App.jsx - public routes correct
+2. ✅ Checked MainLayout - no redirect logic
+3. ✅ Verified controller implementation - correct
+4. ✅ Verified route definitions - looked correct
+5. ✅ Added logging to protect middleware - found it was being called!
+6. ✅ Checked server.js route mounting - FOUND THE BUG!
+
+**Key Insight:**
+The routes *looked* correct because the definitions were fine. The problem was entirely about **ORDER**. Express processes routes sequentially, and catch-all routes with middleware were matching first and blocking everything.
+
+**Debugging Breakthrough:**
+Added logging to protect middleware showing it was being called for public routes. This proved the routes weren't reaching their handlers. Then checked route mounting order and found catch-all routes before specific routes.
+
+**Prevention:**
+Always put specific routes before catch-all routes. When using `app.use('/api', router)`, ensure the router doesn't have `router.use(protect)` or other global middleware that would block public endpoints.
+
+**Time Spent:** 3 hours debugging, 5 minutes fixing once identified.
+
+---
+
+## Real-World Impact
+
+- **Before:** Mobile users couldn't access website, donations blocked
+- **After:** Full public access restored, React app loads properly
+- **Commits:** 12 debugging commits, 1 fix commit, 1 cleanup commit
+- **Deployments:** 6 test deployments, 1 final deployment
+- **Resolution:** Complete fix with no side effects
+
+---
+
+**Project:** MERN Community LMS
+**Date Solved:** 2026-02-02
+**Production Site:** schooloftheprophets.club
+**Commits:** 070bca5 (fix), 2b34625 (cleanup)
+
+---
+
+*This skill documents a critical Express.js routing pattern that cost 3 hours to debug but takes 5 minutes to fix once you know what to look for. Share this knowledge!*

package/skills-library/api-patterns/PAGINATION_PATTERNS.md

@@ -0,0 +1,137 @@
+---
+name: pagination-patterns
+category: api-patterns
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [pagination, api, cursor, offset, rest, graphql]
+difficulty: medium
+---
+
+# Pagination Patterns
+
+## Problem
+
+APIs that return unbounded lists kill performance, waste bandwidth, and crash clients. Offset-based pagination breaks under concurrent writes. Choosing the wrong pattern early means painful migration later.
+
+## Three Patterns
+
+### 1. Offset/Limit (Simple, Fragile)
+
+```javascript
+// GET /api/courses?page=2&limit=20
+router.get('/courses', async (req, res) => {
+  const page = Math.max(1, parseInt(req.query.page) || 1)
+  const limit = Math.min(100, parseInt(req.query.limit) || 20)
+  const offset = (page - 1) * limit
+
+  const [courses, total] = await Promise.all([
+    db.query('SELECT * FROM courses ORDER BY id LIMIT ? OFFSET ?', [limit, offset]),
+    db.query('SELECT COUNT(*) as total FROM courses'),
+  ])
+
+  res.json({
+    data: courses,
+    pagination: {
+      page,
+      limit,
+      total: total[0].total,
+      totalPages: Math.ceil(total[0].total / limit),
+      hasNext: page * limit < total[0].total,
+      hasPrev: page > 1,
+    }
+  })
+})
+```
+
+**Pros:** Easy to implement, supports "jump to page 5."
+**Cons:** Skips/duplicates rows when data changes between pages. Slow on large offsets (DB must scan and discard rows).
+
+### 2. Cursor-Based (Robust, Recommended)
+
+```javascript
+// GET /api/courses?cursor=eyJpZCI6MTAwfQ&limit=20
+router.get('/courses', async (req, res) => {
+  const limit = Math.min(100, parseInt(req.query.limit) || 20)
+  const cursor = req.query.cursor
+    ? JSON.parse(Buffer.from(req.query.cursor, 'base64').toString())
+    : null
+
+  const whereClause = cursor ? 'WHERE id > ?' : ''
+  const params = cursor ? [cursor.id, limit + 1] : [limit + 1]
+
+  const courses = await db.query(
+    `SELECT * FROM courses ${whereClause} ORDER BY id LIMIT ?`,
+    params
+  )
+
+  const hasNext = courses.length > limit
+  if (hasNext) courses.pop()  // Remove the extra row
+
+  const nextCursor = hasNext
+    ? Buffer.from(JSON.stringify({ id: courses[courses.length - 1].id })).toString('base64')
+    : null
+
+  res.json({
+    data: courses,
+    pagination: {
+      nextCursor,
+      hasNext,
+      limit,
+    }
+  })
+})
+```
+
+**Pros:** Consistent results under concurrent writes. Fast (uses index seek, not offset scan).
+**Cons:** Can't jump to arbitrary page. Cursor is opaque to client.
+
+### 3. Keyset (Cursor + Sort)
+
+```javascript
+// When sorting by non-unique fields (e.g., created_at)
+// Use composite cursor: (created_at, id) for uniqueness
+const cursor = { created_at: '2026-02-24T10:00:00Z', id: 150 }
+
+const courses = await db.query(`
+  SELECT * FROM courses
+  WHERE (created_at, id) > (?, ?)
+  ORDER BY created_at, id
+  LIMIT ?
+`, [cursor.created_at, cursor.id, limit + 1])
+```
+
+## Which to Choose
+
+| Scenario | Pattern | Why |
+|----------|---------|-----|
+| Admin dashboard, small dataset | Offset | Jump-to-page needed |
+| Public API, large dataset | Cursor | Consistent, scalable |
+| Real-time feed (chat, activity) | Cursor | Data changes constantly |
+| Search results | Offset | Users expect page numbers |
+| Infinite scroll UI | Cursor | Natural fit |
+
+## Response Envelope
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "abc123",
+    "hasNext": true,
+    "limit": 20
+  }
+}
+```
+
+Always include `hasNext` — clients shouldn't have to guess.
+
+## When to Use
+
+- Any list endpoint returning more than 50 items
+- APIs consumed by mobile apps (bandwidth matters)
+
+## When NOT to Use
+
+- Endpoints that always return small, bounded lists (e.g., user roles)
+- Aggregation endpoints (return a single summary, not a list)