API Endpoints (TRPC)
Relevant source files
The following files were used as context for generating this wiki page:
The application utilizes tRPC (TypeScript Remote Procedure Call) to create a type-safe API layer between the client and server. This approach allows for end-to-end type safety, ensuring that frontend calls to the backend are correctly typed and validated. The API is structured into multiple routers, each designed to run in a specific server environment (Edge, Lambda/Serverful, Async) to optimize for performance and cost.
The core of the tRPC implementation involves a main appRouter that merges specialized routers. The client-side is equipped with multiple tRPC clients, each configured to communicate with a specific router type. This modular architecture enables efficient handling of different kinds of backend tasks, from low-latency streaming chats to long-running asynchronous jobs.
Architecture Overview
The tRPC architecture is designed to direct client requests to the appropriate backend environment based on the nature of the procedure call. The client maintains separate tRPC instances (edgeClient, lambdaClient, asyncClient) that target different API endpoints.
The following diagram illustrates the high-level data flow from the client to the various tRPC routers.
This diagram shows how different client-side tRPC instances target specific API routes, which in turn are handled by their corresponding server-side routers.
Sources: src/libs/trpc/client/index.ts, src/server/routers/_app.ts
tRPC Client Configuration
The client-side setup in src/libs/trpc/client/index.ts is responsible for creating and exporting the tRPC clients used throughout the application. It defines three distinct clients, each tailored for a specific server environment.
edgeClient: Communicates with the Edge Function environment. It uses anhttpBatchLinkfor efficient batching of requests. This client is intended for low-latency, streaming operations.lambdaClient: Communicates with the Serverful/Lambda environment. It also uses anhttpBatchLinkand is designed for longer-running, non-streaming tasks that may require more compute resources.asyncClient: A specialized client that uses a standardhttpLink(no batching) to communicate with the async router, suitable for fire-and-forget tasks or operations that are handled asynchronously.
The following diagram shows the creation of these clients.
Sources: src/libs/trpc/client/index.ts:11-40
tRPC Routers
The backend API is composed of a main appRouter which merges three specialized routers: edgeRouter, lambdaRouter, and asyncRouter. This separation allows for deploying different parts of the API to the most suitable server environment.
Sources: src/server/routers/_app.ts:7-11
App Router (appRouter)
The appRouter is the main router that combines all other routers into a single, unified API structure. It serves as the entry point for all tRPC requests and delegates them to the appropriate sub-router.
| Router | Description | Source File |
|---|---|---|
edge | Contains procedures optimized for Vercel Edge Functions, such as chat streaming. | src/server/routers/edge/index.ts |
lambda | Contains procedures for serverful environments, handling tasks like database interactions. | src/server/routers/lambda/index.ts |
async | Contains procedures for asynchronous tasks that can be processed in the background. | src/server/routers/async/index.ts |
Sources: src/server/routers/_app.ts:7-11
Edge Router (edgeRouter)
This router is designed for procedures that benefit from running on Vercel's Edge Functions, which are geographically distributed for low latency. It primarily handles real-time and streaming functionalities.
| Procedure | Description |
|---|---|
chat.completion | Handles chat message completions, likely with streaming support. |
upload.createS3PreSignedUrl | Creates a pre-signed URL for direct file uploads to an S3 bucket. |
Sources: src/server/routers/edge/index.ts:10-13
Lambda Router (lambdaRouter)
The lambdaRouter is intended for traditional serverful functions (like AWS Lambda). These procedures typically involve more complex business logic, database operations, or tasks that are not suitable for the edge environment's constraints.
| Procedure | Description |
|---|---|
config.getGlobalConfig | Retrieves the global configuration of the application. |
user.getUserState | Fetches the current state for a user. |
user.updateLoginTime | Updates the last login timestamp for a user. |
user.checkHasConversation | Checks if a user has any existing conversations. |
user.resetAllSettings | Resets all settings for the current user. |
Sources: src/server/routers/lambda/index.ts:11-17
Async Router (asyncRouter)
The asyncRouter handles procedures that can be executed asynchronously. These are typically "fire-and-forget" operations where the client does not need to wait for a response.
| Procedure | Description |
|---|---|
user.updateLatestVisitAgent | Asynchronously updates the agent that a user last visited. |
Sources: src/server/routers/async/index.ts:9-11
Example Request Flow
The sequence diagram below demonstrates a typical flow for a chat completion request, which is handled by the edgeRouter.
This flow shows how a type-safe call on the client is translated into an HTTP request to the edge endpoint, processed by the edgeRouter, and how the streaming response is sent back to the client.
Sources: src/libs/trpc/client/index.ts, src/server/routers/edge/index.ts
Summary
The tRPC-based API in lobe-chat provides a robust and type-safe mechanism for client-server communication. By splitting the API into environment-specific routers (edge, lambda, async), the application optimizes for performance, scalability, and cost. The client is intelligently configured with corresponding tRPC instances to seamlessly interact with the appropriate backend services, creating a cohesive and efficient full-stack architecture.