Fix backend startup errors and API proxy issues for external IP access

[croakingtoad]

Summary

This PR fixes critical issues preventing Archon from working correctly when accessed via external IP addresses (not localhost), particularly affecting cloud deployments on DigitalOcean, AWS, etc.

Issues Fixed

• 🐛 Backend Service Startup Failure - Persistent error popup every 10-15 seconds
• 🐛 Configuration check failures - "Failed to fetch" errors preventing Settings from loading
• 🐛 Projects schema verification - "Unable to verify projects schema" warning

Root Cause Analysis

1. Health Endpoint Response Format

The /api/health endpoint was missing required fields that the frontend expected:

• Missing ready: true field caused frontend to think backend wasn't initialized
• Frontend was checking healthData.ready === true but field didn't exist

2. API URL Construction Issues

Frontend services were bypassing the Vite proxy:

• Services constructed full URLs like http://68.183.152.55:8181/api/...
• Should use relative URLs like /api/... to go through Vite proxy at port 3737
• This caused CORS issues and connection failures when accessing from external IPs

3. Static URL Configuration

Service classes set baseUrl once at instantiation:

• Used getApiUrl() which returned the backend port directly
• Didn't update when configuration changed
• Needed to use relative URLs consistently

Changes Made

Backend Changes

• knowledge_api.py: Added ready, credentials_loaded, and schema_valid fields to health endpoint response

Frontend Changes

• api.ts: Modified getApiUrl() to return empty string in development (forces proxy usage)
• MainLayout.tsx: Changed health check to use relative URL /api/health
• FeaturesSection.tsx: Fixed projects health check to use relative URL
• credentialsService.ts: Replaced all API calls with relative URLs
• mcpClientService.ts: Replaced all API calls with relative URLs
• bugReportService.ts: Fixed GitHub bug report endpoint
• testService.ts: Set API_BASE_URL to empty string

Testing Performed

✅ Backend health endpoint returns correct response format ✅ All API calls go through Vite proxy (port 3737) ✅ Settings page loads without errors ✅ Projects toggle works correctly ✅ No more "Backend Service Startup Failure" popups ✅ Configuration checks pass successfully

Deployment Impact

This fix is critical for:

• Cloud deployments (DigitalOcean, AWS, GCP, etc.)
• Docker containerized deployments
• Reverse proxy configurations (nginx, Caddy, etc.)
• Development environments accessed via external IPs
• Any non-localhost access scenarios

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Health status responses now include readiness and validation details.
  • Automatic WebSocket URL resolution for more reliable live connections.

• Bug Fixes

  • API requests consistently route through the dev proxy, improving reliability in development.
  • Clearer, standardized error messages across multiple endpoints for easier troubleshooting.

• Refactor

  • Centralized API and WebSocket URL handling with relative paths for consistent behavior across environments.
  • Unified health checks and service calls to use a single, proxy-friendly API base.

[coderabbitai[bot]]

Walkthrough

Frontend fetches switch to relative /api URLs routed via the Vite proxy; API config adds helpers and public constants for API/WS resolution; MCP client service adopts uniform error parsing and keeps Archon integration; backend knowledge health response includes readiness fields. No public signatures changed.

Changes

Cohort / File(s)	Summary
UI health checks via proxy archon-ui-main/src/components/layouts/MainLayout.tsx, archon-ui-main/src/components/settings/FeaturesSection.tsx	Health check endpoints changed to relative paths (/api/health, /api/projects/health) so requests go through the Vite proxy; logs updated accordingly.
API URL/config centralization archon-ui-main/src/config/api.ts	Simplified getApiUrl to prefer relative URLs; removed window-based URL assembly; added getApiBasePath, getWebSocketUrl; exported API_BASE_URL, API_FULL_URL, WS_URL.
Services moved to relative API paths archon-ui-main/src/services/credentialsService.ts, archon-ui-main/src/services/bugReportService.ts, archon-ui-main/src/services/testService.ts	Replaced dynamic base URL usage with relative /api/... endpoints to route through Vite proxy; logic and signatures unchanged.
MCP client service: proxy + error handling archon-ui-main/src/services/mcpClientService.ts	Switched to relative /api/mcp/... endpoints; standardized error handling by parsing JSON and throwing `Error(error.detail
Backend health payload update python/src/server/api_routes/knowledge_api.py	knowledge_health() healthy response now includes ready, credentials_loaded, and schema_valid fields.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant UI as UI (Browser)
  participant Vite as Vite Dev Proxy
  participant API as Backend API

  UI->>Vite: GET /api/health
  Vite->>API: Forward /api/health
  API-->>Vite: 200 OK {status, ready, credentials_loaded, schema_valid}
  Vite-->>UI: 200 OK ...
  note over UI: Health checks now use relative /api paths via proxy

sequenceDiagram
  autonumber
  participant UI as UI Components
  participant MCP as mcpClientService
  participant API as /api/mcp/...

  UI->>MCP: callClientTool(params)
  MCP->>API: POST /api/mcp/clients/:id/tools/:tool/call
  alt success
    API-->>MCP: 200 OK {result}
    MCP-->>UI: result
  else non-ok
    API-->>MCP: 4xx/5xx {detail:"message"}
    MCP->>MCP: parse JSON, throw Error(detail || default)
    MCP-->>UI: throw Error(...)
    note over MCP,UI: Unified error parsing across MCP endpoints
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• coleam00/Archon#467 — Similar refactor to use proxy-relative API/health URLs and API config adjustments in archon-ui-main.

Poem

I thump my paw—new paths I try,
Through proxy burrows packets fly.
MCP now speaks its errors clear,
Health fields blink: “all ready here.”
With whiskers twitching, I approve—
Hop, hop! Our routes now smoothly move. 🐇✨

✨ Finishing Touches

• [ ] 📝 Generate Docstrings

🧪 Generate unit tests

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coleam00]

Thanks for this @croakingtoad! I will be reviewing PRs this weekend 👍

[stevepresley]

FYI - @croakingtoad 's fixes are also in my PR relating the localhost/versus external IP being used incorrectly on the /health call
https://github.com/coleam00/Archon/pull/573

[coleam00]

@croakingtoad - we have cleaned up some things that have caused merge conflicts and potentially resolved the first issue (backend startup errors). Would you be able to test/rebase if needed?

[leex279]

Closed => no response