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
   # .env.local
   NEXT_PUBLIC_API_URL=http://localhost:4000
   ```

2. Update your API calls (if using relative paths):
   ```typescript
   // 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:
   ```typescript
   // 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:

```bash
# 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