igny8/CRITICAL-ISSUE-ROUTER-CONTEXT-ERROR.md

# CRITICAL ISSUE: Router Context Error After Git Commits

**Date:** December 8, 2025  
**Status:** 🔴 CRITICAL - Blocks deployment  
**Priority:** P0 - Must fix before any git push to remote

---

## Problem Summary

After committing backend changes to git and syncing with remote, **frontend pages break** with React Router context errors. The system is currently working but **will break** when the 6 modified backend files are pushed to remote.

### Affected Pages
1. `/planner/keywords` - Planner Keywords page
2. `/writer/tasks` - Writer Tasks page  
3. `/sites` - Sites management page
4. `/thinker/prompts` - Thinker Prompts page
5. `/automation` - Automation page
6. `/setup/add-keywords` - Add Keywords setup page

### Error Pattern

**Primary Error:**
```
Error: useLocation() may be used only in the context of a <Router> component.
    at ModuleNavigationTabs (ModuleNavigationTabs.tsx:22:20)
```

**Secondary Error:**
```
Error: useNavigate() may be used only in the context of a <Router> component.
```

**Associated API Errors (related to permission fixes):**
```
403 Forbidden: /api/v1/auth/sites/5/sectors/
403 Forbidden: /api/v1/auth/sites/
404 Not Found: /api/v1/billing/transactions/balance/
```

---

## Root Cause Analysis

### NOT a Code Issue
The code works fine in development and after fresh rebuild. The Router errors are **NOT** caused by the backend permission fixes.

### ACTUAL Cause: Docker Build Cache Invalidation Failure

**The Problem Chain:**
1. Backend code changes are committed to git
2. Git push triggers remote sync
3. Docker Compose sees changed files
4. **Docker does NOT properly rebuild frontend container** (uses stale cache)
5. Frontend serves old JavaScript bundles with mismatched module boundaries
6. React Router hooks fail because component tree structure changed
7. Pages crash with "useLocation/useNavigate not in Router context"

**Why This Happens:**
- Frontend `Dockerfile.dev` uses `npm install` (not `npm ci`)
- `package.json` changes don't always trigger full rebuild
- Docker layer caching is too aggressive
- `node_modules` volume persists stale dependencies
- Vite HMR works during dev, but production bundle gets out of sync

---

## Current Workaround (Manual Fix)

**When errors occur, run these steps:**

```bash
# 1. Remove ALL containers in Portainer (manual deletion via UI)

# 2. Rebuild infrastructure containers
cd /data/app
docker compose -f docker-compose.yml -p igny8-infra up -d
sleep 3

# 3. Rebuild application containers  
cd /data/app/igny8
docker compose -f docker-compose.app.yml -p igny8-app up -d

# 4. Clear user session
# - Log out from app
# - Clear all cookies
# - Log back in
```

**Result:** All pages work again ✅

---

## Files That Will Trigger This Issue

**Currently modified (unstaged) backend files:**
```
backend/igny8_core/api/base.py          - Superuser bypass in ViewSets
backend/igny8_core/api/permissions.py   - Bypass in permission classes  
backend/igny8_core/api/throttles.py     - Bypass in rate throttling
backend/igny8_core/auth/middleware.py   - Session validation bypass
backend/igny8_core/auth/utils.py        - Account validation bypass
backend/igny8_core/modules/billing/urls.py - Billing endpoint alias
```

**When these are pushed to remote → frontend breaks**

---

## Permanent Fix Required

### Solution A: Fix Docker Build Cache (RECOMMENDED)

**1. Update `frontend/Dockerfile.dev`:**

```dockerfile
# Before:
RUN npm install

# After:
COPY package.json package-lock.json ./
RUN npm ci --prefer-offline --no-audit
COPY . .
```

**Explanation:**
- `npm ci` does clean install (deletes node_modules first)
- Separate COPY layers ensure package.json changes invalidate cache
- `--prefer-offline` speeds up rebuild with local cache

**2. Update `docker-compose.app.yml` frontend service:**

```yaml
volumes:
  - ./frontend:/app
  - /app/node_modules  # ← ADD THIS LINE
```

**Explanation:**
- Excludes `node_modules` from volume mount
- Prevents host `node_modules` from overriding container's
- Forces Docker to use freshly installed dependencies

**3. Update deployment commands to use `--no-cache` flag:**

```bash
# Development rebuild (when issues occur)
docker compose -f docker-compose.app.yml build --no-cache frontend
docker compose -f docker-compose.app.yml up -d frontend

# Production deployment (always use)
docker compose -f docker-compose.app.yml build --no-cache
docker compose -f docker-compose.app.yml up -d
```

### Solution B: Add Build Verification Step

**Add to deployment script:**

```bash
#!/bin/bash
# deploy_frontend.sh

echo "Building frontend with cache busting..."
docker compose -f docker-compose.app.yml build --no-cache frontend

echo "Checking build artifacts..."
docker run --rm igny8-app-frontend ls -la /app/dist/

echo "Deploying frontend..."
docker compose -f docker-compose.app.yml up -d frontend

echo "Waiting for health check..."
sleep 5
curl -f https://app.igny8.com || echo "WARNING: Frontend not responding"
```

---

## Why Backend Changes Break Frontend

**This seems counterintuitive but here's why:**

1. **Backend changes get committed** → triggers rebuild process
2. **docker-compose.app.yml rebuilds ALL services** (backend + frontend)
3. **Backend rebuilds correctly** (Django reloads Python modules)
4. **Frontend rebuild FAILS SILENTLY** (uses cached layers)
5. **Old frontend bundle** tries to connect to **new backend API**
6. **React component tree structure mismatch** → Router context errors

**The Fix:**
- Ensure frontend ALWAYS rebuilds when ANY file in docker-compose.app.yml changes
- Use `--no-cache` on deployments
- Add build hash verification

---

## Testing Plan

### Before Pushing to Remote

**1. Test current system works:**
```bash
curl -I https://app.igny8.com/planner/keywords
curl -I https://app.igny8.com/writer/tasks
curl -I https://app.igny8.com/sites
```

**2. Apply Docker fixes:**
- Update `frontend/Dockerfile.dev`
- Update `docker-compose.app.yml`
- Test rebuild with `--no-cache`

**3. Verify pages load:**
- Login as dev@igny8.com
- Visit all 6 affected pages
- Check browser console for errors

**4. Commit and push:**
```bash
git add backend/
git commit -m "Fix superuser/developer access bypass"
git push origin main
```

**5. Monitor production:**
- SSH to server
- Watch docker logs: `docker logs -f igny8_frontend`
- Check all 6 pages still work

### If Errors Still Occur

Run the manual workaround:
1. Remove containers in Portainer
2. Rebuild infra + app
3. Clear cookies + re-login

---

## Impact Assessment

**Current Status:**
- ✅ System working locally
- ✅ All pages functional after rebuild
- ⚠️ **6 backend files uncommitted** (permission fixes)
- 🔴 **Cannot push to remote** (will break production)

**Deployment Blocked Until:**
- [ ] Docker build cache fix implemented
- [ ] Frontend Dockerfile.dev updated
- [ ] docker-compose.app.yml volume exclusion added
- [ ] Deployment script uses --no-cache
- [ ] Test push to staging branch first

**Business Impact:**
- Superuser/developer access fixes are ready but **cannot be deployed**
- Production system stuck on old code
- Manual rebuild required after every deployment
- High risk of breaking production

---

## Next Steps

**Immediate (Before Any Git Push):**
1. ⏸️ **DO NOT commit or push the 6 backend files yet**
2. 🔧 Fix `frontend/Dockerfile.dev` first
3. 🔧 Update `docker-compose.app.yml` volumes
4. ✅ Test full rebuild with --no-cache
5. ✅ Verify all 6 pages work
6. 📝 Commit Docker fixes first
7. 📝 Then commit backend permission fixes
8. 🚀 Push to remote in correct order

**After Router Fix:**
1. User will test account/billing pages (user-level)
2. Check for permission leakage in admin menu
3. Verify superuser-only access works correctly
4. Test user menu vs admin menu isolation

---

## Related Issues

**From Previous Documentation:**
- Issue D: Docker Build Cache (FINAL-IMPLEMENTATION-REQUIREMENTS.md)
- Session Contamination (CRITICAL-ISSUE-C.md)  
- Subscription Creation Gap (Issue B)

**New Findings:**
- Router context errors are **symptom** of build cache issue
- Backend commits trigger the problem (unexpected)
- Frontend needs proper dependency invalidation
- Cookie clearing required after rebuild (session state persists)

---

## References

**Files Modified (Current Session):**
```
✅ backend/igny8_core/auth/middleware.py - Added superuser bypass
✅ backend/igny8_core/api/permissions.py - Added bypass to 4 classes
✅ backend/igny8_core/api/base.py - Added bypass to ViewSet querysets
✅ backend/igny8_core/auth/utils.py - Added bypass to validation
✅ backend/igny8_core/modules/billing/urls.py - Added endpoint alias
✅ backend/igny8_core/api/throttles.py - Added throttle bypass
```

**Database Changes (Current Session):**
```
✅ Deleted duplicate free-trial plan (ID: 7)
✅ Renamed enterprise → internal (System/Superuser only)
✅ 5 plans now active: free, starter, growth, scale, internal
```

**Documentation Created:**
```
- IMPLEMENTATION-COMPLETE-DEC-8-2025.md (comprehensive summary)
- QUICK-FIX-IMPLEMENTATION-SUMMARY.md (initial fixes)
- SYSTEM-AUDIT-REPORT-2025-12-08.md (audit results)
- CRITICAL-ISSUE-ROUTER-CONTEXT-ERROR.md (this document)
```

---

## Conclusion

**The system is working perfectly right now**, but **will break when code is pushed to remote** due to Docker build cache issues. 

**Priority:** Fix Docker caching BEFORE committing the 6 backend permission files.

**DO NOT PUSH TO REMOTE until Docker fixes are tested and verified.**