Next.js API Proxy Handlers
Relevant source files
The following files were used as context for generating this wiki page:
Next.js API Proxy Handlers in the TrueLens application act as an intermediary layer between the frontend client and the Python-based FastAPI backend. These handlers are implemented using Next.js Route Handlers (App Router) to manage request validation, data transformation, and secure communication with the internal microservices.
The primary purpose of these proxies is to bridge the gap between the Next.js frontend and the BACKEND_URL (defaulting to http://127.0.0.1:8000), ensuring that requests are properly formatted and that snake_case responses from the Python backend are converted into the camelCase format expected by the TypeScript frontend.
Sources: truelens-app/src/app/api/v1/scans/route.ts:3-5, truelens-app/src/app/api/v1/documents/route.ts:3-5
Architecture and Data Flow
The proxy system follows a standard request-response lifecycle where the Next.js server validates incoming client data before forwarding it to the backend.
Request Proxying Logic
- Client Request: The frontend components (e.g.,
ScanPageorDocumentsPage) send requests to the local/api/v1/*routes. - Validation: The Route Handler performs initial checks, such as verifying text length or file presence.
- Forwarding: The handler reconstructs the request (using
fetch) and sends it to theBACKEND_URL. - Response Transformation: The handler receives the backend response, maps snake_case fields to camelCase, and returns a unified JSON object to the client.
The following sequence diagram illustrates this flow:
Core Proxy Endpoints
Content Scanning Proxy
The scanning proxy handles both URL and raw text analysis. It enforces a minimum text length of 50 characters to ensure meaningful AI analysis.
- Endpoint:
POST /api/v1/scans - Backend Destination:
${BACKEND_URL}/api/v1/scans/ - Field Mapping:
content_type→contentTypetrust_score→trustScorescan_duration→scanDuration
Sources: truelens-app/src/app/api/v1/scans/route.ts:18-53
Document Verification Proxy
This proxy manages multi-part form data for file uploads. It reads raw bytes from the incoming file and reconstructs a FormData object to preserve file metadata when communicating with the backend.
- Endpoint:
POST /api/v1/documents - Backend Destination:
${BACKEND_URL}/api/v1/documents/verify - Features: Includes cryptographic signature mapping if provided by the backend.
Sources: truelens-app/src/app/api/v1/documents/route.ts:7-50
Fact-Check Proxy
A simpler proxy that forwards search queries for real-time verification. It requires a minimum query length of 3 characters.
- Endpoint:
GET /api/v1/fact-check - Backend Destination:
${BACKEND_URL}/api/v1/fact-check?query=...
Sources: truelens-app/src/app/api/v1/fact-check/route.ts:7-25
API Configuration Summary
| Feature | Handler Path | Backend Target | Method | Input Required |
|---|---|---|---|---|
| Scan Submission | /api/v1/scans | /api/v1/scans/ | POST | url or text |
| Scan Retrieval | /api/v1/scans/[id] | /api/v1/scans/[id] | GET | id parameter |
| Doc Verification | /api/v1/documents | /api/v1/documents/verify | POST | file (FormData) |
| Fact-Check | /api/v1/fact-check | /api/v1/fact-check | GET | query (string) |
Sources: truelens-app/src/app/developers/page.tsx:13-58, truelens-app/src/app/api/v1/fact-check/route.ts:13-20
Implementation Details
Data Transformation Example
The proxy handlers are responsible for converting backend naming conventions to frontend standards. This is critical for maintaining type safety in the TypeScript environment.
// Example from scans proxy
const scan = {
...data,
contentType: data.content_type,
trustScore: data.trust_score,
scanDuration: data.scan_duration,
createdAt: data.created_at,
completedAt: data.completed_at
};
Sources: truelens-app/src/app/api/v1/scans/route.ts:46-53
Error Handling
The handlers implement consistent error catching to prevent backend failures from crashing the frontend server. If the backend returns a non-OK status, the proxy attempts to parse the backend's error detail or provides a fallback message.
Conclusion
The Next.js API Proxy Handlers provide a robust abstraction layer for TrueLens, centralizing validation and data normalization. By acting as a gateway to the FastAPI backend, they allow the frontend to interact with a clean, consistent API while offloading complex ML and document analysis tasks to specialized microservices.