API Routing & Web Server

Relevant source files

The following files were used as context for generating this wiki page:

• src/web/routes/index.ts
• src/web/api.ts
• scripts/gates/checks/guard/route-table.ts
• dashboard/views/shell/index.ts
• scripts/gates/checks/doc/check-docs.ts
• README_EN.md

The API Routing & Web Server module manages all incoming HTTP requests for the freebuff-proxy service. It acts as a multi-faced gateway that separates OpenAI-compatible proxy traffic, administrative control panel APIs, and static web dashboard assets. The system ensures that downstream agents interact with a standard API surface while administrators use a secure, authenticated web interface for management.

Sources: src/web/routes/index.ts:1-18, README_EN.md:39-50

Request Dispatching Architecture

The server categorizes every request into one of three "faces" based on the URL pathname. This strict separation prevents administrative APIs from being exposed to the public proxy endpoint and ensures appropriate response formats for different client types.

• Proxy Face: Handles standard AI completions and model listings.
• Console Face: Provides administrative APIs for account, user, and proxy management.
• Static Face: Serves the web dashboard assets.

Routing Logic Flow

The system uses a faceOf function to determine the destination for each request. Unknown paths or incorrectly formatted paths default to the static asset server to avoid leaking proxy or API structure.

Core API Endpoints

The server exposes two primary categories of endpoints: the OpenAI-compatible surface and the internal management API.

Downstream Proxy Interface

These endpoints follow the OpenAI specification to ensure compatibility with existing AI clients and agents.

Method	Path	Purpose
POST	/v1/chat/completions	Main path for chat completions (session + passthrough)
GET	/v1/models	Returns the available model catalog
GET	/healthz	Liveness probe for the service

Sources: README_EN.md:62-68, scripts/gates/checks/guard/route-table.ts:21-25

Internal Management API

Administrative endpoints are prefixed with /api/ and require a valid session cookie.

Method	Path	Purpose
POST	/api/auth/login	Authenticates users and establishes sessions
GET	/api/me	Retrieves current user profile and API key
POST	/api/system/restart	Triggers a service restart
GET	/api/overview	Provides account pool and session snapshots

Sources: dashboard/views/shell/index.ts:160-165, dashboard/views/shell/index.ts:315-320, src/web/routes/index.ts:140-145

Web Console & Single Page Application (SPA)

The web dashboard is a Single Page Application that avoids complex build chains. It renders TypeScript source files directly in the browser by stripping types at runtime.

Client-Side Routing

The dashboard uses a hash-based routing mechanism (#overview, #settings, etc.). It caches rendered DOM nodes for each page to preserve user input and UI state when switching between tabs.

Component Roles & Implementation

The web server implementation is modularized to maintain small file sizes and clear boundaries.

• src/web/api.ts: Serves as a thin facade for the control plane API. It exports createWebApi to shield external callers from internal file restructuring.
• src/web/routes/index.ts: Acts as the main entry point for administrative requests. It builds a buildContext containing shared dependencies like userStore, proxyStore, and modelStore.
• src/server/route-table.ts: Defines the boundary logic that routes traffic between the proxy engine and the web server.

Sources: src/web/api.ts:1-9, src/web/routes/index.ts:33-58

Security & Authentication Gate

The server implements a session required gate for all /api/ requests.

1. Public Zone: Allows access to the /api/auth/login endpoint.
2. Session Check: Validates the user session via getSessionUser(req, ctx).
3. 401 Unauthorized: Returns a JSON error if the session is missing or expired.
4. Domain Routing: Dispatches to specific handlers (Control or Inventory domains) if authenticated.

Sources: src/web/routes/index.ts:128-147

Summary

The API Routing & Web Server module provides a robust multi-tenant interface for the Freebuff Proxy. It strictly separates agent traffic from administrative traffic, implements an efficient SPA dashboard with DOM caching, and maintains high code quality through automated route-table verification gates. This architecture ensures stability while supporting complex features like real-time session monitoring and multi-account scheduling.