# quorinex/freebuff2api architecture

> Architecture diagram of the GitHub repository quorinex/freebuff2api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quorinex/freebuff2api
- Repository: https://github.com/quorinex/freebuff2api

## Overview

Freebuff2API is a proxy that accepts OpenAI-compatible requests and translates them to Freebuff’s backend API. Clients can list models, request chat completions, or use the documented Claude-compatible endpoints; chat requests resolve a model to an agent, acquire a managed run, call upstream, and return a compatible response. Token counting is another API capability. Run management handles token pools, session readiness, rotation, and run cleanup. The README documents API-key authentication and outbound proxy support. Some handler and conversion wiring is omitted because excerpts are partial; uncertain links are left out.

Main entry points: [`server.go`](https://github.com/quorinex/freebuff2api/blob/main/server.go) (HTTP API), [`upstream.go`](https://github.com/quorinex/freebuff2api/blob/main/upstream.go) (Upstream client), [`main.go`](https://github.com/quorinex/freebuff2api/blob/main/main.go) (Process entry), [`run_manager.go`](https://github.com/quorinex/freebuff2api/blob/main/run_manager.go) (Run manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API server"]
  node_main["Process entry<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_server["HTTP API<br/>[server.go]"]
end

subgraph group_compat["Compatibility"]
  node_registry["Model registry<br/>[models.go]"]
  node_anthropic["Claude translation<br/>[anthropic.go]"]
  node_token_count["Token counting<br/>[token_count.go]"]
end

subgraph group_runs["Run orchestration"]
  node_runs["Run manager<br/>[run_manager.go]"]
  node_session["Free-session handling<br/>[free_session.go]"]
end

subgraph group_backend["Backend access"]
  node_upstream["Upstream client<br/>[upstream.go]"]
end

node_openai_client(("OpenAI clients"))
node_claude_client(("Claude clients"))
node_freebuff(("Freebuff backend"))
node_agent_source(("Agent model source"))
node_proxy(("HTTP proxy"))

node_main -->|"loads settings"| node_config
node_main -->|"starts server"| node_server
node_main -->|"starts registry"| node_registry
node_openai_client -->|"sends API requests"| node_server
node_claude_client -->|"sends API requests"| node_server
node_server -->|"resolves models"| node_registry
node_server -->|"translates Claude requests"| node_anthropic
node_server -->|"counts tokens"| node_token_count
node_server -->|"acquires run"| node_runs
node_server -->|"sends chat request"| node_upstream
node_registry -->|"fetches agent mapping"| node_agent_source
node_runs -->|"manages sessions"| node_session
node_runs -->|"starts and finishes runs"| node_upstream
node_session -->|"calls session APIs"| node_upstream
node_upstream -->|"sends backend requests"| node_freebuff
node_upstream -.->|"routes outbound traffic"| node_proxy

click node_main "https://github.com/quorinex/freebuff2api/blob/main/main.go"
click node_config "https://github.com/quorinex/freebuff2api/blob/main/config.go"
click node_server "https://github.com/quorinex/freebuff2api/blob/main/server.go"
click node_registry "https://github.com/quorinex/freebuff2api/blob/main/models.go"
click node_anthropic "https://github.com/quorinex/freebuff2api/blob/main/anthropic.go"
click node_token_count "https://github.com/quorinex/freebuff2api/blob/main/token_count.go"
click node_runs "https://github.com/quorinex/freebuff2api/blob/main/run_manager.go"
click node_session "https://github.com/quorinex/freebuff2api/blob/main/free_session.go"
click node_upstream "https://github.com/quorinex/freebuff2api/blob/main/upstream.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config,node_server,node_openai_client,node_claude_client toneBlue
class node_registry,node_anthropic,node_token_count toneAmber
class node_runs,node_session toneMint
class node_upstream toneRose
class node_freebuff,node_agent_source,node_proxy toneIndigo
```

## Components

### API server

- [Process entry](https://github.com/quorinex/freebuff2api/blob/main/main.go): `main.go`
- [Configuration](https://github.com/quorinex/freebuff2api/blob/main/config.go): `config.go`
- [HTTP API](https://github.com/quorinex/freebuff2api/blob/main/server.go): `server.go`

### Compatibility

- [Model registry](https://github.com/quorinex/freebuff2api/blob/main/models.go): `models.go`
- [Claude translation](https://github.com/quorinex/freebuff2api/blob/main/anthropic.go): `anthropic.go`
- [Token counting](https://github.com/quorinex/freebuff2api/blob/main/token_count.go): `token_count.go`

### Run orchestration

- [Run manager](https://github.com/quorinex/freebuff2api/blob/main/run_manager.go): `run_manager.go`
- [Free-session handling](https://github.com/quorinex/freebuff2api/blob/main/free_session.go): `free_session.go`

### Backend access

- [Upstream client](https://github.com/quorinex/freebuff2api/blob/main/upstream.go): `upstream.go`

### Other components

- **OpenAI clients**
- **Claude clients**
- **Freebuff backend**
- **Agent model source**
- **HTTP proxy**

## Connections

- Process entry → Configuration: loads settings
- Process entry → HTTP API: starts server
- Process entry → Model registry: starts registry
- OpenAI clients → HTTP API: sends API requests
- Claude clients → HTTP API: sends API requests
- HTTP API → Model registry: resolves models
- HTTP API → Claude translation: translates Claude requests
- HTTP API → Token counting: counts tokens
- HTTP API → Run manager: acquires run
- HTTP API → Upstream client: sends chat request
- Model registry → Agent model source: fetches agent mapping
- Run manager → Free-session handling: manages sessions
- Run manager → Upstream client: starts and finishes runs
- Free-session handling → Upstream client: calls session APIs
- Upstream client → Freebuff backend: sends backend requests
- Upstream client → HTTP proxy: routes outbound traffic