File Path for the Main Proxy Route Handlers in FreeLLMAPI: Complete Server Architecture Guide

The main proxy route handlers in FreeLLMAPI are located at server/src/routes/proxy.ts, which exports the proxyRouter Express router and supporting utilities for authentication, logging, and request forwarding.

FreeLLMAPI is an open-source Express-based proxy layer for language model APIs maintained by tashfeenahmed. Locating the exact file path for the main proxy route handlers is critical for developers customizing request routing, implementing middleware, or extending the server's functionality. This guide identifies the specific TypeScript module and its architectural relationships within the codebase.

Primary Location of the Proxy Route Handlers

The central proxy functionality resides in server/src/routes/proxy.ts within the FreeLLMAPI repository. This file implements the Express Router that handles all LLM proxy endpoints, including /v1/completions and /v1/chat/completions.

The module serves as the primary interface between incoming client requests and the underlying provider forwarding logic found in server/src/lib/proxy.ts. According to the FreeLLMAPI source code, this router manages the complete request lifecycle from token validation through response streaming.

Key Exports and Utilities

The server/src/routes/proxy.ts file exports several named utilities that support request handling across the application architecture.

proxyRouter

The proxyRouter export is the Express Router instance that registers all proxy-related endpoints. It integrates with authentication middleware and coordinates with lower-level forwarding functions before sending requests to underlying LLM providers.

Security and Extraction Helpers

• timingSafeStringEqual: Performs constant-time comparison of API tokens to prevent timing attacks during authentication validation.
• extractApiToken: Parses bearer tokens from incoming Authorization headers for use in access control checks.

Session and Tracing Utilities

• getStickyModel and setStickyModel: Implement session persistence logic that keeps clients on consistent model selections across multiple requests.
• getRequestGroupId: Generates deterministic identifiers used for rate-limiting and analytics tracking.
• traceRouteEvent: Emits observability data for monitoring platforms and logging pipelines.

Error Classification and Streaming

• isRetryableError and isPaymentRequiredError: Classify provider responses to determine appropriate client feedback and retry behavior.
• streamChunkText: Normalizes streaming response chunks from various providers into standardized text formats.

How to Import and Use the Proxy Router

These code examples demonstrate practical integration patterns for the proxy handlers in an Express application.

Registering the Router in Express

import express from 'express';
import { proxyRouter } from './routes/proxy';

const app = express();

// Apply global middleware
app.use(express.json());

// Mount the proxy router under the API path
app.use('/api', proxyRouter);

// Start the server
app.listen(3000, () => console.log('FreeLLMAPI listening on port 3000'));

Using Helper Functions in Middleware

import { extractApiToken, logRequest } from './routes/proxy';

// Custom middleware implementation
app.use((req, res, next) => {
  const token = extractApiToken(req);
  if (!token) return res.status(401).send('Missing API token');
  logRequest(req, token);
  next();
});

Implementing Sticky Model Selection

import { getStickyModel, setStickyModel } from './routes/proxy';

function handleChat(req, res) {
  const stickyId = getStickyModel(req.body.messages, req.headers['x-session-id']);
  const modelId = stickyId ?? determineBestModel(req);
  // Forward request using selected model
  setStickyModel(req.body.messages, modelId, req.headers['x-session-id']);
}

Related Files in the Routing Architecture

While server/src/routes/proxy.ts contains the main handlers, several adjacent files complete the routing system:

• server/src/routes/responses.ts: Imports proxyRouter to build chat completion responses using shared token-validation logic.
• server/src/routes/models.ts: Exposes model-listing endpoints that work alongside the proxy system for provider discovery.
• server/src/app.ts: Configures the Express application instance and mounts all route modules including proxyRouter.
• server/src/lib/proxy.ts: Contains low-level functions for actual HTTP request forwarding to specific LLM providers.

Summary

• The main proxy route handlers reside in server/src/routes/proxy.ts in the tashfeenahmed/freellmapi repository.
• This file exports proxyRouter, the primary Express router for LLM API endpoints, alongside security and utility functions.
• Supporting utilities include extractApiToken for authentication, getStickyModel for session persistence, and isRetryableError for error handling.
• Related modules like responses.ts and app.ts integrate with the proxy router to complete the request lifecycle.

Frequently Asked Questions

Where are the proxy route handlers defined in FreeLLMAPI?

The proxy route handlers are defined in server/src/routes/proxy.ts according to the FreeLLMAPI source code. This TypeScript file contains the Express router that manages all proxy endpoints for forwarding requests to language model providers.

What is the purpose of the proxyRouter export?

The proxyRouter export is the main Express Router instance that registers endpoints such as /v1/completions and /v1/chat/completions. It serves as the entry point for request validation, authentication, and forwarding to the underlying LLM services implemented in server/src/lib/proxy.ts.

How does FreeLLMAPI handle authentication in the proxy routes?

Authentication is handled through the extractApiToken function, which parses bearer tokens from request headers, and timingSafeStringEqual, which performs constant-time token comparison to prevent timing attacks. These utilities are exported from server/src/routes/proxy.ts and used across the routing system.

What other files work with the main proxy router?

The proxy router collaborates with server/src/routes/responses.ts for chat completions, server/src/routes/models.ts for model listing, and server/src/app.ts for application mounting. The actual HTTP forwarding logic resides separately in server/src/lib/proxy.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}