ROUTING_FIX_ANALYSIS.md

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):

# Line 27 in deployed version
raise RuntimeError("Not found")

Local Code (Current - FIXED):

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):

# 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)

# 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

# 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:

@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

# 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:

   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:

   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