# SAAP API Routing Fix - Root Cause Analysis

## 🔍 Problem Identified

**Error Pattern in HuggingFace:**
```
File "/app/spa_static_files.py", line 27, in get_response
    raise RuntimeError("Not found")
RuntimeError: Not found
```

## ✅ Root Cause Discovery

**Deployed Code (HuggingFace - OLD):**
```python
# Line 27 in deployed version
raise RuntimeError("Not found")
```

**Local Code (Current - FIXED):**
```python
try:
    return await super().get_response(path, scope)
except Exception:
    # File not found → serve index.html for SPA routing
    return FileResponse(os.path.join(self.directory, "index.html"))
```

## 🎯 Core Issue

**Version Mismatch:** HuggingFace deployment has old `spa_static_files.py` that raises exception instead of serving `index.html` for SPA fallback routing.

**Current Local Code Status:** ✅ ALREADY CORRECT

## 📋 Routing Configuration Analysis

### Current `backend/main.py` Structure (CORRECT):

```python
# Line ~1200: All API routes defined first
@app.get("/api")
@app.get("/health")
@app.get("/api/v1/health")
@app.get("/api/v1/agents")  # ← Critical agent list endpoint
@app.post("/api/v1/agents/{agent_id}/chat")
# ... all other API routes ...

# Line ~1890: Static files mounted LAST (correct order)
app.mount("/", SPAStaticFiles(directory=frontend_dist, html=True), name="static")
```

### Why This Works (Theory):

1. **API Routes First**: FastAPI processes routes in definition order
2. **Catch-All Last**: `app.mount("/", ...)` acts as catch-all for unmatched routes
3. **SPAStaticFiles**: Serves static files OR index.html (SPA fallback)

### Why It's Failing in HuggingFace:

**Old spa_static_files.py raises exception** → FastAPI error handler → 500 Internal Server Error

## ✅ Solution

### Option 1: Trigger Redeployment (RECOMMENDED)
```bash
# Commit current (correct) code
git add backend/spa_static_files.py
git commit -m "fix(api): correct SPA fallback routing - serve index.html instead of RuntimeError"
git push huggingface main

# HuggingFace auto-deploys on push
```

### Option 2: Verify & Force Rebuild
```bash
# Check deployed version
curl https://hwandji-saap.hf.space/api/v1/agents -v

# If still failing, force rebuild in HuggingFace UI:
# Settings → Factory Reboot
```

## 🔧 Additional Safeguards

### Add Explicit API Route Logging

**In `backend/main.py` after API route definitions:**
```python
@app.on_event("startup")
async def log_routes():
    """Log all registered routes for debugging"""
    routes = []
    for route in app.routes:
        if hasattr(route, 'path'):
            routes.append(f"{route.methods if hasattr(route, 'methods') else 'MOUNT'}: {route.path}")
    logger.info(f"📍 Registered Routes ({len(routes)}):")
    for r in sorted(routes):
        logger.info(f"   {r}")
```

## 🧪 Testing Checklist

After deployment:

- [ ] `GET /api/v1/agents` returns 200 with agents list
- [ ] `GET /` returns Vue.js index.html (200)
- [ ] `GET /assets/*` returns static files (200/304)
- [ ] `GET /nonexistent` returns index.html (SPA routing)
- [ ] Frontend displays agents correctly

## 📊 Verification Commands

```bash
# Test API endpoint
curl https://hwandji-saap.hf.space/api/v1/agents

# Expected response (200):
# {"agents": [...], "total": 7, "active": 7, ...}

# Test SPA fallback
curl https://hwandji-saap.hf.space/random-path -I

# Expected: 200 OK, Content-Type: text/html
```

## 🚀 Deployment Steps

1. **Commit Fix:**
   ```bash
   git status
   git add backend/spa_static_files.py
   git commit -m "fix(api): SPA fallback routing - FileResponse instead of RuntimeError"
   ```

2. **Push to HuggingFace:**
   ```bash
   git push huggingface main
   ```

3. **Monitor Deployment:**
   - Watch HuggingFace build logs
   - Wait for "Running" status
   - Test `/api/v1/agents` endpoint

4. **Verify Frontend:**
   - Open https://hwandji-saap.hf.space
   - Check agents display
   - Test chat functionality

## 📝 Summary

**Issue:** Old `spa_static_files.py` on HuggingFace raises `RuntimeError` → 500 errors
**Local Status:** Code already fixed with `FileResponse` fallback ✅
**Action Required:** Commit + Push to trigger HuggingFace redeployment
**Expected Resolution:** API routing works, agents display correctly

---

**Next Step:** Execute deployment commands to push fixed code to HuggingFace