From 41a51af6b4ac7c18486aceebf78916f83f2a1d9c Mon Sep 17 00:00:00 2001
From: Samir Boulahtit <samir.boulahtit@wizard.lu>
Date: Sat, 22 Nov 2025 15:55:56 +0100
Subject: [PATCH] docs: update troubleshooting documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update troubleshooting guide with latest fixes and solutions for
common development issues encountered during CMS implementation
and shop frontend development.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/development/troubleshooting.md | 140 ++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)

diff --git a/docs/development/troubleshooting.md b/docs/development/troubleshooting.md
index 1fe290fe..e9785df0 100644
--- a/docs/development/troubleshooting.md
+++ b/docs/development/troubleshooting.md
@@ -13,6 +13,7 @@ Common PyCharm issues and their solutions for the development team.
 - [Performance Issues](#performance-issues)
 - [Git Integration Issues](#git-integration-issues)
 - [Database Tool Issues](#database-tool-issues)
+- [Frontend Asset Loading Issues](#frontend-asset-loading-issues)
 
 ---
 
@@ -342,6 +343,145 @@ DATABASE_URL=postgresql://user:password@localhost:5432/letzshop_db
 
 ---
 
+## Frontend Asset Loading Issues
+
+### Problem
+
+- Tailwind CSS styles not loading
+- Alpine.js not initializing
+- Frontend pages look unstyled
+- Console errors about missing CSS/JS files
+- App doesn't work offline
+
+### Solution 1: Verify CDN Fallback Files Exist
+
+All frontends use CDN with local fallback. Check that local copies exist:
+
+```bash
+# From project root
+ls -lh static/shared/css/tailwind.min.css
+ls -lh static/shared/js/vendor/alpine.min.js
+```
+
+**Expected output:**
+```
+-rw-r--r-- 1 user user 2.9M static/shared/css/tailwind.min.css
+-rw-r--r-- 1 user user  44K static/shared/js/vendor/alpine.min.js
+```
+
+**If files are missing:**
+```bash
+# Download Tailwind CSS
+cd static/shared/css
+curl -o tailwind.min.css https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css
+
+# Download Alpine.js
+cd ../js/vendor
+curl -o alpine.min.js https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js
+```
+
+### Solution 2: Check Browser Console
+
+Open DevTools (F12) and check the Console tab for errors:
+
+**Common errors:**
+- `GET http://localhost:8000/static/shared/css/tailwind.min.css [404 Not Found]` → File missing
+- `Alpine.js CDN failed, loading local copy...` → Normal fallback behavior
+- `Uncaught ReferenceError: Alpine is not defined` → Alpine.js failed to load
+
+### Solution 3: Test CDN Fallback Behavior
+
+To verify fallback works correctly:
+
+1. **Start application:**
+   ```bash
+   uvicorn app.main:app --reload
+   ```
+
+2. **Test with CDN blocked:**
+   - Open browser DevTools (F12)
+   - Go to Network tab
+   - Add request blocking rule for `cdn.jsdelivr.net`
+   - Reload page
+
+3. **Verify fallback:**
+   - Check Console for: `⚠️ Alpine.js CDN failed, loading local copy...`
+   - Check Network tab shows local files loaded
+   - Page should still work normally
+
+### Solution 4: Verify Static Files Mounting
+
+Check that FastAPI is serving static files correctly:
+
+**In `app/main.py`:**
+```python
+from fastapi.staticfiles import StaticFiles
+
+app.mount("/static", StaticFiles(directory="static"), name="static")
+```
+
+**Test static file serving:**
+```bash
+# With app running, test directly:
+curl http://localhost:8000/static/shared/css/tailwind.min.css | head -n 5
+curl http://localhost:8000/static/shared/js/vendor/alpine.min.js | head -n 5
+```
+
+### Solution 5: File Permissions
+
+If files exist but return 403 Forbidden:
+
+```bash
+# Fix permissions
+chmod 644 static/shared/css/tailwind.min.css
+chmod 644 static/shared/js/vendor/alpine.min.js
+chmod 755 static/shared/css
+chmod 755 static/shared/js/vendor
+```
+
+### Solution 6: For Offline Development
+
+If working completely offline, the CDN will always fail. Verify:
+
+1. **Console shows fallback message** (expected behavior)
+2. **Local files load successfully**
+3. **Page functions normally**
+
+**To suppress CDN warnings when offline:**
+- Accept that CDN will fail (expected)
+- Fallback mechanism handles it automatically
+- Or modify templates to use local-only (see [CDN Fallback Strategy](../frontend/cdn-fallback-strategy.md#optimization-strategies))
+
+### Solution 7: Network Issues
+
+If both CDN and local files fail intermittently:
+
+1. **Check browser cache:**
+   - Open DevTools → Network tab
+   - Check "Disable cache" option
+   - Hard reload: Ctrl+Shift+R
+
+2. **Clear browser cache completely:**
+   - Browser Settings → Privacy → Clear browsing data
+   - Select "Cached images and files"
+   - Clear data
+
+3. **Check for firewall/proxy issues:**
+   ```bash
+   # Test CDN accessibility
+   curl https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css | head -n 5
+   ```
+
+### Related Documentation
+
+See [CDN Fallback Strategy](../frontend/cdn-fallback-strategy.md) for complete details on:
+- How the fallback mechanism works
+- Updating local asset files
+- Production deployment considerations
+- Air-gapped deployment setup
+
+---
+
 ## Quick Checklist for New Developers
 
 When setting up PyCharm for the first time: