Refact: Allow API Server to Start Without Built WebUI Assets

[danielaskdd]

Refact: Allow API Server to Start Without Built WebUI Assets

Problem

Previously, the API server would hard-exit during startup (sys.exit(1)) if the WebUI frontend wasn't built, making it impossible to run API-only deployments or environments where the UI is built separately. This created several issues:

• Brittle containerized deployments - Containers would fail to start if WebUI assets were missing
• Development friction - Developers had to build the WebUI before testing API changes
• API-only use cases blocked - Users who only needed the REST API still required WebUI assets
• 404 errors - Accessing /webui paths with missing assets resulted in confusing 404 errors

Solution

Refactored the frontend asset checking and mounting logic to enable graceful degradation:

1. Non-blocking WebUI Check

• Changed check_frontend_build() to return a tuple (assets_exist, is_outdated) instead of calling sys.exit(1)
• Display yellow warning messages instead of red errors when assets are missing
• Server continues startup without WebUI functionality

2. Conditional Route Mounting

• WebUI static assets (/webui) only mounted when assets exist
• Added fallback redirect routes for /webui and /webui/ → /docs when assets missing
• Root path (/) intelligently redirects based on WebUI availability:
  • → /webui when WebUI is available
  • → /docs (Swagger UI) when WebUI is missing

3. Health Endpoint Enhancement

• Added webui_available: boolean field to /health response
• Comprehensive Swagger/OpenAPI documentation for the field
• Enables monitoring systems to detect WebUI availability status

4. User Experience

• Clear build instructions displayed in warning messages
• Users never encounter unexpected 404 errors
• Swagger UI always available as fallback interface

Benefits

✅ API-only deployments - Server starts successfully without WebUI
✅ Container-friendly - No brittle startup failures
✅ Development flexibility - Build UI when ready, not required upfront
✅ Better monitoring - /health endpoint reports WebUI status
✅ Clear feedback - Yellow warnings with actionable build instructions
✅ Backward compatible - Existing deployments with built WebUI work unchanged

Testing

Manual testing verified:

• Server starts successfully with missing WebUI assets
• Warning messages display correctly with build instructions
• Root redirect (/) → /docs when WebUI missing
• /webui and /webui/ redirect to /docs when assets missing
• /health endpoint includes webui_available: false when assets missing
• All API routes remain functional without WebUI
• Swagger UI documentation shows updated /health response schema

[danielaskdd]

@codex review