# fairyspace/arena2api architecture

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

- Interactive diagram: https://gitdiagram.com/fairyspace/arena2api
- Repository: https://github.com/fairyspace/arena2api

## Overview

Arena2API turns Arena.ai models into an OpenAI-compatible local API. A client sends a model listing or chat request to the Python proxy; the proxy uses extension-pushed credentials, cookies, models, and reCAPTCHA tokens to call Arena.ai, then returns a complete response or translated SSE stream. Chrome and Firefox extensions implement parallel browser-side collection and messaging paths, with a popup for connection status and manual actions. The README documents the major capabilities; internal server stages are grouped from its documented flow, since the excerpt does not expose all implementations.

Main entry points: [`server.py`](https://github.com/fairyspace/arena2api/blob/master/server.py) (OpenAI Proxy), [`extension/background.js`](https://github.com/fairyspace/arena2api/blob/master/extension/background.js) (Background Worker), [`extension-firefox/background.js`](https://github.com/fairyspace/arena2api/blob/master/extension-firefox/background.js) (Background Script), [`extension/content.js`](https://github.com/fairyspace/arena2api/blob/master/extension/content.js) (Content Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Proxy API"]
  node_proxy["OpenAI Proxy<br/>[server.py]"]
end

subgraph group_server["Request Processing"]
  node_state[("Auth and Model State<br/>[server.py]")]
  node_catalog["Model Catalog<br/>[server.py]"]
  node_arena_request["Arena Request<br/>[server.py]"]
  node_response["Response Conversion<br/>[server.py]"]
end

subgraph group_chrome["Chrome Extension"]
  node_chrome_bg["Background Worker<br/>[background.js]"]
  node_chrome_bridge["Content Bridge<br/>[content.js]"]
  node_chrome_page["Page Injector<br/>[injector.js]"]
  node_chrome_popup["Status Popup<br/>[popup.js]"]
end

subgraph group_firefox["Firefox Extension"]
  node_firefox_bg["Background Script<br/>[background.js]"]
  node_firefox_bridge["Content Bridge<br/>[content.js]"]
  node_firefox_page["Page Injector<br/>[injector.js]"]
  node_firefox_popup["Status Popup<br/>[popup.js]"]
end

node_client(("API Client"))
node_arena(("Arena.ai"))

node_client -->|"sends API request"| node_proxy
node_proxy -->|"lists or matches"| node_catalog
node_proxy -->|"checks connection and credentials"| node_state
node_proxy -->|"builds Arena request"| node_arena_request
node_arena_request -->|"calls Arena API"| node_arena
node_arena -->|"returns SSE"| node_response
node_response -->|"returns OpenAI response"| node_client
node_chrome_page -->|"posts page data"| node_chrome_bridge
node_chrome_bridge -->|"sends extension messages"| node_chrome_bg
node_chrome_bg -->|"requests token or cookies"| node_chrome_bridge
node_chrome_bg -->|"pushes extension data"| node_proxy
node_chrome_popup -->|"requests status and actions"| node_chrome_bg
node_firefox_page -->|"posts page data"| node_firefox_bridge
node_firefox_bridge -->|"sends extension messages"| node_firefox_bg
node_firefox_bg -->|"requests token or cookies"| node_firefox_bridge
node_firefox_bg -->|"pushes extension data"| node_proxy
node_firefox_popup -->|"requests status and actions"| node_firefox_bg

click node_proxy "https://github.com/fairyspace/arena2api/blob/master/server.py"
click node_state "https://github.com/fairyspace/arena2api/blob/master/server.py"
click node_catalog "https://github.com/fairyspace/arena2api/blob/master/server.py"
click node_arena_request "https://github.com/fairyspace/arena2api/blob/master/server.py"
click node_response "https://github.com/fairyspace/arena2api/blob/master/server.py"
click node_chrome_bg "https://github.com/fairyspace/arena2api/blob/master/extension/background.js"
click node_chrome_bridge "https://github.com/fairyspace/arena2api/blob/master/extension/content.js"
click node_chrome_page "https://github.com/fairyspace/arena2api/blob/master/extension/injector.js"
click node_chrome_popup "https://github.com/fairyspace/arena2api/blob/master/extension/popup.js"
click node_firefox_bg "https://github.com/fairyspace/arena2api/blob/master/extension-firefox/background.js"
click node_firefox_bridge "https://github.com/fairyspace/arena2api/blob/master/extension-firefox/content.js"
click node_firefox_page "https://github.com/fairyspace/arena2api/blob/master/extension-firefox/injector.js"
click node_firefox_popup "https://github.com/fairyspace/arena2api/blob/master/extension-firefox/popup.js"

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_proxy,node_client toneBlue
class node_state,node_catalog,node_arena_request,node_response toneAmber
class node_chrome_bg,node_chrome_bridge,node_chrome_page,node_chrome_popup toneMint
class node_firefox_bg,node_firefox_bridge,node_firefox_page,node_firefox_popup toneRose
class node_arena toneIndigo
```

## Components

### Proxy API

- [OpenAI Proxy](https://github.com/fairyspace/arena2api/blob/master/server.py): `server.py`

### Request Processing

- [Auth and Model State](https://github.com/fairyspace/arena2api/blob/master/server.py): `server.py`
- [Model Catalog](https://github.com/fairyspace/arena2api/blob/master/server.py): `server.py`
- [Arena Request](https://github.com/fairyspace/arena2api/blob/master/server.py): `server.py`
- [Response Conversion](https://github.com/fairyspace/arena2api/blob/master/server.py): `server.py`

### Chrome Extension

- [Background Worker](https://github.com/fairyspace/arena2api/blob/master/extension/background.js): `extension/background.js`
- [Content Bridge](https://github.com/fairyspace/arena2api/blob/master/extension/content.js): `extension/content.js`
- [Page Injector](https://github.com/fairyspace/arena2api/blob/master/extension/injector.js): `extension/injector.js`
- [Status Popup](https://github.com/fairyspace/arena2api/blob/master/extension/popup.js): `extension/popup.js`

### Firefox Extension

- [Background Script](https://github.com/fairyspace/arena2api/blob/master/extension-firefox/background.js): `extension-firefox/background.js`
- [Content Bridge](https://github.com/fairyspace/arena2api/blob/master/extension-firefox/content.js): `extension-firefox/content.js`
- [Page Injector](https://github.com/fairyspace/arena2api/blob/master/extension-firefox/injector.js): `extension-firefox/injector.js`
- [Status Popup](https://github.com/fairyspace/arena2api/blob/master/extension-firefox/popup.js): `extension-firefox/popup.js`

### Other components

- **API Client**
- **Arena.ai**

## Connections

- API Client → OpenAI Proxy: sends API request (evidence: `README.md`)
- OpenAI Proxy → Model Catalog: lists or matches (evidence: `README.md`)
- OpenAI Proxy → Auth and Model State: checks connection and credentials (evidence: `README.md`)
- OpenAI Proxy → Arena Request: builds Arena request (evidence: `README.md`)
- Arena Request → Arena.ai: calls Arena API (evidence: `README.md`)
- Arena.ai → Response Conversion: returns SSE (evidence: `README.md`)
- Response Conversion → API Client: returns OpenAI response (evidence: `README.md`)
- Page Injector → Content Bridge: posts page data (evidence: `extension/content.js`)
- Content Bridge → Background Worker: sends extension messages (evidence: `extension/content.js`)
- Background Worker → Content Bridge: requests token or cookies (evidence: `extension/background.js`)
- Background Worker → OpenAI Proxy: pushes extension data (evidence: `extension/background.js`)
- Status Popup → Background Worker: requests status and actions (evidence: `extension/popup.js`)
- Page Injector → Content Bridge: posts page data (evidence: `extension-firefox/content.js`)
- Content Bridge → Background Script: sends extension messages (evidence: `extension-firefox/content.js`)
- Background Script → Content Bridge: requests token or cookies (evidence: `extension-firefox/background.js`)
- Background Script → OpenAI Proxy: pushes extension data (evidence: `extension-firefox/background.js`)
- Status Popup → Background Script: requests status and actions (evidence: `extension-firefox/popup.js`)