Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Freebuff-proxy transforms Freebuff free quota into an OpenAI-compatible API endpoint. The system manages multi-account pools, session admissions, and request shaping while passing streaming and non-streaming responses back to downstream agents.
Sources: README_EN.md:10-15, CLAUDE.md:37-38
System Components
The project uses a split-runtime architecture to ensure compatibility with official upstream protocols while providing a robust Node.js-based management interface.
Core Architecture Layers
| Component | Runtime | Primary Responsibility |
|---|---|---|
| Main Service | Node.js 22 | User management, API key validation, proxy pool management, and account scheduling. |
| CLI Bridge | Bun | Official protocol implementation, device signing, and RPC delegation for upstream calls. |
| Dashboard | Browser | Web-based management console for accounts, users, and global configuration. |
| Data Layer | Filesystem | Persistence for credentials, user data, and proxy settings in /data. |
Sources: README_EN.md:43-46, CLAUDE.md:65-68, cli-bridge/AGENTS.md:7-10
Component Interaction
The following diagram illustrates the request flow from a downstream agent through the proxy to the Freebuff upstream.
The Node service acts as the management gatekeeper, while cli-bridge handles the specific byte-for-byte official client request shaping.
Sources: README_EN.md:120-125, cli-bridge/AGENTS.md:7-10
Protocol and Signal Translation
The system includes a dedicated translation layer to ensure that downstream client requests appear as official client requests to the upstream.
Signal Translation Logic
The src/upstream/signals module translates tool names and parameter structures. It maps downstream tool definitions to official 37-tool sets to avoid detection as a third-party client.
- Downlink: Translates client tool names to official names before sending to upstream.
- Uplink: Restores official tool names to the original client names in the response.
- Parameter Mapping: Rewrites fields and prunes additional properties to satisfy upstream schemas.
Sources: src/upstream/signals/AGENTS.md:7-15, README_EN.md:126-130
Data Persistence and Configuration
The application follows a "configuration via UI" philosophy, where the filesystem serves as the single source of truth for runtime data.
- Proxies: Stored in
/data/proxies.json. Changes take effect immediately via the console. - Accounts: Credentials reside in
/data/credentials/. The system handles multi-account scheduling and cool-down states. - Users: Managed in
/data/users.json, including API keys (sk-fb-...) and roles. - Scheduling Ledger: Account availability and buy-in states are tracked in
/data/account-state.jsonto survive restarts.
Sources: README_EN.md:92-105, CLAUDE.md:65-68
Front-end Architecture
The dashboard is a lightweight, zero-build TypeScript application.
- No Bundler: Files are served directly by the Node service using
stripTypeScriptTypes. - Lazy Loading: Large resources, such as the Monaco Editor (3.7MB), are only loaded when required to maintain fast initial page loads.
- State Management: Managed via
dashboard/lib/state.ts, with routing handled by a hash-based system indashboard/views/shell/.
Sources: dashboard/AGENTS.md:7-15, dashboard/AGENTS.md:19-25
Summary
The Freebuff-proxy architecture prioritizes official protocol fidelity by delegating upstream communication to a Bun-based bridge. The Node.js main service provides a management layer that enables multi-account pooling, quota protection, and user-friendly web configuration, ensuring all critical data persists in the /data volume.
Sources: README_EN.md:132-138, CLAUDE.md:65-68