hono-proxy/README-NEXTJS-COMPATIBILITY.md

Hono Proxy - Next.js Compatibility Guide

This Hono proxy server is designed to be a drop-in replacement for the Next.js API routes, providing 100% compatibility with the existing frontend.

Endpoint Mapping

The Hono proxy implements all endpoints exactly as they exist in the Next.js implementation:

Next.js API Route	Backend Endpoint	Method	Description
/api/colpali-search	/fetch_results	GET	Search with ColPali ranking
/api/full-image	/full_image	GET	Get full resolution image
/api/query-suggestions	/suggestions	GET	Autocomplete suggestions
/api/similarity-maps	/get_sim_map	GET	Generate similarity visualization
/api/visual-rag-chat	/get-message	GET (SSE)	Stream chat responses

Parameter Compatibility

All query parameters are preserved exactly as in Next.js:

Search

GET /api/colpali-search?query=annual+report&ranking=hybrid

Full Image

GET /api/full-image?docId=abc123

Suggestions

GET /api/query-suggestions?query=ann

Similarity Maps

GET /api/similarity-maps?queryId=123&idx=0&token=report&tokenIdx=2

Visual RAG Chat (SSE)

GET /api/visual-rag-chat?queryId=123&query=What+is+revenue&docIds=abc,def,ghi

Frontend Integration

To use the Hono proxy with your Next.js frontend:

1. Update your environment variable:

   # .env.local
   NEXT_PUBLIC_API_URL=http://localhost:4000
   

2. Update your API calls (if using relative paths):

   // If currently using relative paths like:
   const response = await fetch('/api/colpali-search?query=...');
   
   // Change to:
   const response = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/colpali-search?query=...`);
   

3. Or use a base URL configuration:

   // utils/api.ts
   export const API_BASE = process.env.NEXT_PUBLIC_API_URL || '';
   
   // In components:
   const response = await fetch(`${API_BASE}/api/colpali-search?query=...`);
   

Response Format

All responses are identical to what Next.js returns:

• Search results include the same Vespa response structure
• Full images return { base64_image: "..." }
• Suggestions return { suggestions: [...] }
• Similarity maps return HTML content
• SSE chat streams the same event format

Additional Features

While maintaining 100% compatibility, the Hono proxy adds:

• Caching: Search results and images are cached
• Rate Limiting: Prevents backend overload
• Health Checks: Monitor backend availability
• Request IDs: Track requests across systems
• Performance: Faster response times with caching

Migration Path

1. No Frontend Changes Required: The Hono proxy mimics Next.js API routes exactly
2. Gradual Migration: Can run both Next.js and Hono simultaneously on different ports
3. Environment-based: Use environment variables to switch between implementations

Testing Compatibility

Test script to verify all endpoints work:

# Search
curl "http://localhost:4000/api/colpali-search?query=annual+report&ranking=hybrid"

# Full Image  
curl "http://localhost:4000/api/full-image?docId=abc123"

# Suggestions
curl "http://localhost:4000/api/query-suggestions?query=ann"

# Similarity Map
curl "http://localhost:4000/api/similarity-maps?queryId=123&idx=0&token=report&tokenIdx=2"

# Visual RAG Chat (SSE)
curl -N "http://localhost:4000/api/visual-rag-chat?queryId=123&query=What+is+revenue&docIds=abc,def"

Benefits Over Next.js API Routes

1. Independent Scaling: Scale API separately from frontend
2. Better Performance: Dedicated API server with caching
3. Deployment Flexibility: Deploy anywhere (Docker, K8s, serverless)
4. Monitoring: Built-in health checks and metrics
5. Security: Rate limiting and request validation