# lm-arena/lm-arena.github.io architecture

> Architecture diagram of the GitHub repository lm-arena/lm-arena.github.io, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lm-arena/lm-arena.github.io
- Repository: https://github.com/lm-arena/lm-arena.github.io

## Overview

LM Arena is a browser-based, self-hosted LLM arena: users choose models and a mode, submit prompts, and receive streamed responses from live ephemeral inference endpoints, with optional browser inference fallback. It also supports compare, analyze, debate, image-field extraction, gesture input, and model fleet administration. Edges reflect README statements and shown imports/calls; unsampled admin and deployment details are not expanded beyond documented behavior.

Main entry points: [`app/chat/frontend/src/Playground.tsx`](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/Playground.tsx) (Arena workspace), [`app/chat/frontend/src/utils/streaming.ts`](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/utils/streaming.ts) (Stream transport), [`app/chat/frontend/src/hooks/useSessionController.ts`](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/hooks/useSessionController.ts) (Session controller), [`app/chat/frontend/src/hooks/useModelsManager.ts`](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/hooks/useModelsManager.ts) (Model selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Arena frontend"]
  node_playground["Arena workspace<br/>[Playground.tsx]"]
  node_modelmanager["Model selection"]
  node_session["Session controller"]
  node_chatview["Chat interaction<br/>[ChatView.tsx]"]
  node_arena["Arena cards<br/>[ArenaCanvas.tsx]"]
  node_stream["Stream transport<br/>[streaming.ts]"]
  node_thinkparse["Thinking parser<br/>[thinkingParser.ts]"]
  node_analyze["Analyze mode<br/>[analyzeEngine.ts]"]
  node_debate["Debate mode<br/>[debateEngine.ts]"]
  node_transcript["Discussion transcript"]
  node_extract["Image extraction<br/>[ExtractView.tsx]"]
  node_vlm["Vision extraction<br/>[vlmExtract.ts]"]
  node_gesture["Gesture controls<br/>[GestureControl.tsx]"]
  node_gesturectx["Gesture state<br/>[GestureContext.tsx]"]
end

subgraph group_inference["Model inference"]
  node_browser["Browser inference"]
  node_server["Inference launcher"]
  node_wrapper["llama.cpp wrapper"]
end

subgraph group_registry["Tunnel discovery"]
  node_worker[("Tunnel registry<br/>[worker.js]")]
end

subgraph group_catalog["Model catalog"]
  node_config["Model definitions<br/>[models.py]"]
  node_modelsjson["Model metadata"]
end

node_user(("User"))
node_runner["Actions runner"]
node_tunnel["Cloudflare tunnel"]
node_cloudflare["Cloudflare service"]
node_githubpages["GitHub Pages"]

node_user -->|"uses"| node_playground
node_playground -->|"loads selection"| node_modelmanager
node_playground -->|"starts sessions"| node_session
node_playground -->|"renders arena"| node_arena
node_playground -.->|"renders chat"| node_chatview
node_modelmanager -->|"fetches metadata"| node_modelsjson
node_modelmanager -->|"discovers live models"| node_worker
node_session -->|"requests streams"| node_stream
node_session -->|"parses chunks"| node_thinkparse
node_session -->|"runs analysis"| node_analyze
node_session -->|"runs debate"| node_debate
node_chatview -->|"requests streams"| node_stream
node_analyze -->|"streams completions"| node_stream
node_debate -->|"streams turns"| node_stream
node_playground -.->|"shows discussion"| node_transcript
node_playground -.->|"offers extraction"| node_extract
node_extract -->|"extracts fields"| node_vlm
node_gesture -->|"updates state"| node_gesturectx
node_playground -.->|"offers controls"| node_gesture
node_stream -.->|"falls back"| node_browser
node_runner -->|"starts inference"| node_server
node_server -->|"launches wrapper"| node_wrapper
node_wrapper -->|"reads model config"| node_config
node_runner -->|"opens tunnel"| node_tunnel
node_tunnel -->|"registers endpoint"| node_worker
node_worker -.->|"uses service"| node_cloudflare
node_stream -->|"streams chat directly"| node_tunnel
node_githubpages -->|"serves app"| node_user
node_config -->|"defines catalog"| node_modelsjson

click node_playground "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/Playground.tsx"
click node_modelmanager "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/hooks/useModelsManager.ts"
click node_session "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/hooks/useSessionController.ts"
click node_chatview "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/ChatView.tsx"
click node_arena "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/arenas/ArenaCanvas.tsx"
click node_stream "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/utils/streaming.ts"
click node_thinkparse "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/utils/thinkingParser.ts"
click node_analyze "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/engines/analyzeEngine.ts"
click node_debate "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/engines/debateEngine.ts"
click node_transcript "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/DiscussionTranscript.tsx"
click node_extract "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/ExtractView.tsx"
click node_vlm "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/utils/vlmExtract.ts"
click node_gesture "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/GestureControl.tsx"
click node_gesturectx "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/context/GestureContext.tsx"
click node_browser "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/utils/browserInference.ts"
click node_config "https://github.com/lm-arena/lm-arena.github.io/blob/main/config/models.py"
click node_server "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/shared/inference_server.py"
click node_wrapper "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/shared/llama_server_wrapper.py"
click node_worker "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/tunnel-registry/worker.js"
click node_modelsjson "https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/hooks/useModelsManager.ts"

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_playground,node_modelmanager,node_session,node_chatview,node_arena,node_stream,node_thinkparse,node_analyze,node_debate,node_transcript,node_extract,node_vlm,node_gesture,node_gesturectx,node_user toneBlue
class node_browser,node_server,node_wrapper toneAmber
class node_worker toneMint
class node_config,node_modelsjson toneRose
class node_runner,node_tunnel,node_cloudflare,node_githubpages toneIndigo
```

## Components

### Arena frontend

- [Arena workspace](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/Playground.tsx): `app/chat/frontend/src/Playground.tsx`
- [Model selection](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/hooks/useModelsManager.ts): `app/chat/frontend/src/hooks/useModelsManager.ts`
- [Session controller](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/hooks/useSessionController.ts): `app/chat/frontend/src/hooks/useSessionController.ts`
- [Chat interaction](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/ChatView.tsx): `app/chat/frontend/src/components/ChatView.tsx`
- [Arena cards](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/arenas/ArenaCanvas.tsx): `app/chat/frontend/src/components/arenas/ArenaCanvas.tsx`
- [Stream transport](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/utils/streaming.ts): `app/chat/frontend/src/utils/streaming.ts`
- [Thinking parser](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/utils/thinkingParser.ts): `app/chat/frontend/src/utils/thinkingParser.ts`
- [Analyze mode](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/engines/analyzeEngine.ts): `app/chat/frontend/src/engines/analyzeEngine.ts`
- [Debate mode](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/engines/debateEngine.ts): `app/chat/frontend/src/engines/debateEngine.ts`
- [Discussion transcript](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/DiscussionTranscript.tsx): `app/chat/frontend/src/components/DiscussionTranscript.tsx`
- [Image extraction](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/ExtractView.tsx): `app/chat/frontend/src/components/ExtractView.tsx`
- [Vision extraction](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/utils/vlmExtract.ts): `app/chat/frontend/src/utils/vlmExtract.ts`
- [Gesture controls](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/components/GestureControl.tsx): `app/chat/frontend/src/components/GestureControl.tsx`
- [Gesture state](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/context/GestureContext.tsx): `app/chat/frontend/src/context/GestureContext.tsx`

### Model inference

- [Browser inference](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/utils/browserInference.ts): `app/chat/frontend/src/utils/browserInference.ts`
- [Inference launcher](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/shared/inference_server.py): `app/shared/inference_server.py`
- [llama.cpp wrapper](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/shared/llama_server_wrapper.py): `app/shared/llama_server_wrapper.py`

### Tunnel discovery

- [Tunnel registry](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/tunnel-registry/worker.js): `app/tunnel-registry/worker.js`

### Model catalog

- [Model definitions](https://github.com/lm-arena/lm-arena.github.io/blob/main/config/models.py): `config/models.py`
- [Model metadata](https://github.com/lm-arena/lm-arena.github.io/blob/main/app/chat/frontend/src/hooks/useModelsManager.ts): `app/chat/frontend/src/hooks/useModelsManager.ts`

### Other components

- **User**
- **Actions runner**
- **Cloudflare tunnel**
- **Cloudflare service**
- **GitHub Pages**

## Connections

- User → Arena workspace: uses
- Arena workspace → Model selection: loads selection (evidence: `app/chat/frontend/src/Playground.tsx`)
- Arena workspace → Session controller: starts sessions (evidence: `app/chat/frontend/src/Playground.tsx`)
- Arena workspace → Arena cards: renders arena (evidence: `app/chat/frontend/src/Playground.tsx`)
- Arena workspace → Chat interaction: renders chat (evidence: `app/chat/frontend/src/Playground.tsx`)
- Model selection → Model metadata: fetches metadata (evidence: `app/chat/frontend/src/hooks/useModelsManager.ts`)
- Model selection → Tunnel registry: discovers live models (evidence: `app/chat/frontend/src/hooks/useModelsManager.ts`)
- Session controller → Stream transport: requests streams (evidence: `app/chat/frontend/src/hooks/useSessionController.ts`)
- Session controller → Thinking parser: parses chunks (evidence: `app/chat/frontend/src/hooks/useSessionController.ts`)
- Session controller → Analyze mode: runs analysis (evidence: `app/chat/frontend/src/hooks/useSessionController.ts`)
- Session controller → Debate mode: runs debate (evidence: `app/chat/frontend/src/hooks/useSessionController.ts`)
- Chat interaction → Stream transport: requests streams (evidence: `app/chat/frontend/src/components/ChatView.tsx`)
- Analyze mode → Stream transport: streams completions (evidence: `app/chat/frontend/src/engines/analyzeEngine.ts`)
- Debate mode → Stream transport: streams turns (evidence: `app/chat/frontend/src/engines/debateEngine.ts`)
- Arena workspace → Discussion transcript: shows discussion (evidence: `app/chat/frontend/src/Playground.tsx`)
- Arena workspace → Image extraction: offers extraction (evidence: `app/chat/frontend/src/Playground.tsx`)
- Image extraction → Vision extraction: extracts fields (evidence: `app/chat/frontend/src/components/ExtractView.tsx`)
- Gesture controls → Gesture state: updates state (evidence: `app/chat/frontend/src/components/GestureControl.tsx`)
- Arena workspace → Gesture controls: offers controls (evidence: `app/chat/frontend/src/Playground.tsx`)
- Stream transport → Browser inference: falls back (evidence: `app/chat/frontend/src/utils/streaming.ts`)
- Actions runner → Inference launcher: starts inference
- Inference launcher → llama.cpp wrapper: launches wrapper (evidence: `app/shared/inference_server.py`)
- llama.cpp wrapper → Model definitions: reads model config (evidence: `app/shared/llama_server_wrapper.py`)
- Actions runner → Cloudflare tunnel: opens tunnel
- Cloudflare tunnel → Tunnel registry: registers endpoint
- Tunnel registry → Cloudflare service: uses service
- Stream transport → Cloudflare tunnel: streams chat directly
- GitHub Pages → User: serves app
- Model definitions → Model metadata: defines catalog
