Archon icon indicating copy to clipboard operation
Archon copied to clipboard

Consolidate duplicate API health endpoints

Open Wirasm opened this issue 3 months ago • 0 comments

Problem

We currently have multiple competing health endpoints that create confusion and maintenance overhead:

Current Problematic Architecture:

  • Main app: /health and /api/health (in main.py)
  • Knowledge API: /api/health (in knowledge_api.py) - ROUTE COLLISION
  • Projects API: /api/projects/health
  • Settings API: /api/settings/health
  • MCP API: /api/mcp/health
  • Bug Report API: /api/bug-report/health

Issues:

  1. Route collision: Two different /api/health endpoints exist
  2. Confusing for clients: Frontend doesn't know which health endpoint to call
  3. Duplicate logic: Migration detection logic had to be added to knowledge health because that's what frontend actually hits
  4. Maintenance burden: Health logic scattered across multiple files
  5. Inconsistent responses: Different endpoints return different response formats

Evidence:

Frontend logs show it's calling /api/health but hitting the knowledge module's health endpoint (returns service: 'knowledge-api') instead of the main health endpoint (should return service: 'archon-backend').

Proposed Solution

Consolidate to single canonical health endpoint:

Option 1: Single Comprehensive Health (Recommended)

  • Remove all module-specific health endpoints
  • Have ONE /api/health endpoint in main.py that checks:
    • Database connectivity
    • Schema migrations
    • Credential initialization
    • Critical service dependencies
  • Frontend calls one endpoint, gets complete system status

Option 2: Hierarchical Health

  • Keep /api/health in main.py as primary endpoint
  • Move module healths to non-colliding paths: /api/knowledge/health, /api/projects/health
  • Main health calls module healths and aggregates response
  • Frontend still calls one canonical endpoint

Benefits

  • No more route collisions
  • Single source of truth for system health
  • Easier to maintain health logic
  • Clearer for frontend developers
  • Consistent response format
  • Better debugging experience

Acceptance Criteria

  • [ ] Remove duplicate /api/health endpoints
  • [ ] Consolidate health logic into main health endpoint
  • [ ] Update frontend to call single canonical health endpoint
  • [ ] Test that migration detection still works
  • [ ] Ensure no breaking changes for existing health monitoring

Impact

High Priority: This architectural issue is causing real problems with our migration detection system and creates ongoing maintenance burden.

Wirasm avatar Aug 26 '25 08:08 Wirasm