# chaoticmindv/master-v-bates architecture

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

- Interactive diagram: https://gitdiagram.com/chaoticmindv/master-v-bates
- Repository: https://github.com/chaoticmindv/master-v-bates

## Overview

Arena Desktop embeds arena.ai in a Windows desktop window and serves a local Flask interface. The principal workflow is user message → local UI/API → embedded arena.ai session → streamed reply; when a folder is selected, the app also mediates model tool calls under permission settings. The README documents modes, modalities, accounts, chat history, and Code-mode file copying. Several subsystem links below are documented rather than verified from complete source; unsampled implementation details are not inferred.

Main entry points: [`arena/web/app.py`](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/web/app.py) (Flask API), [`arena/tools/__init__.py`](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/tools/__init__.py) (Tool registry), [`arena/engine.py`](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/engine.py) (Embedded engine), [`arena/desktop.py`](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/desktop.py) (Desktop window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Desktop experience"]
  node_desktop["Desktop window<br/>[desktop.py]"]
  node_frontend["Local web UI<br/>[app.js]"]
  node_webapi["Flask API<br/>[app.py]"]
end

subgraph group_conversation["Conversation runtime"]
  node_engine["Embedded engine<br/>[engine.py]"]
  node_contracts["Wire contracts<br/>[contracts.py]"]
  node_api["Arena API client<br/>[api.py]"]
  node_models["Model catalog<br/>[models.py]"]
  node_compat["OpenAI compatibility<br/>[openai_compat.py]"]
end

subgraph group_identity["Accounts and state"]
  node_accounts["Account management<br/>[accounts.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_config[("Settings and storage<br/>[config.py]")]
end

subgraph group_tools["Workspace tools"]
  node_agent["Tool-call agent<br/>[agent.py]"]
  node_permissions["Permission modes<br/>[permissions.py]"]
  node_filetools["File operations<br/>[file_tools.py]"]
  node_toolregistry["Tool registry<br/>[__init__.py]"]
  node_shelltools["Shell commands<br/>[shell_tools.py]"]
  node_browsermcp["Browser tools<br/>[browser_mcp.py]"]
  node_workspace["Code workspace<br/>[workspace.py]"]
end

node_user(("User"))
node_arena{{"Arena.ai"}}

node_user -->|"uses"| node_desktop
node_desktop -->|"starts"| node_webapi
node_desktop -->|"hosts"| node_engine
node_user -->|"sends messages"| node_frontend
node_frontend -->|"requests"| node_webapi
node_webapi -->|"dispatches chats"| node_engine
node_engine -->|"sends and streams"| node_arena
node_webapi -->|"uses client"| node_api
node_webapi -->|"formats requests"| node_contracts
node_engine -->|"uses formats"| node_contracts
node_webapi -->|"loads catalog"| node_models
node_webapi -->|"serves compatibility"| node_compat
node_webapi -->|"manages accounts"| node_accounts
node_accounts -->|"uses authentication"| node_auth
node_accounts -->|"persists account data"| node_config
node_webapi -->|"reads and writes"| node_config
node_webapi -->|"runs tool calls"| node_agent
node_webapi -->|"enforces modes"| node_permissions
node_agent -.->|"dispatches tools"| node_toolregistry
node_toolregistry -->|"registers"| node_filetools
node_toolregistry -->|"registers"| node_shelltools
node_toolregistry -->|"registers"| node_browsermcp
node_webapi -->|"copies Code outputs"| node_workspace

click node_desktop "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/desktop.py"
click node_frontend "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/web/static/app.js"
click node_webapi "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/web/app.py"
click node_engine "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/engine.py"
click node_contracts "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/contracts.py"
click node_api "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/api.py"
click node_models "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/models.py"
click node_compat "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/web/openai_compat.py"
click node_accounts "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/accounts.py"
click node_auth "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/auth.py"
click node_config "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/config.py"
click node_agent "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/agent.py"
click node_permissions "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/permissions.py"
click node_filetools "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/tools/file_tools.py"
click node_toolregistry "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/tools/__init__.py"
click node_shelltools "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/tools/shell_tools.py"
click node_browsermcp "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/tools/browser_mcp.py"
click node_workspace "https://github.com/chaoticmindv/master-v-bates/blob/main/arena/workspace.py"

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_desktop,node_frontend,node_webapi,node_user toneBlue
class node_engine,node_contracts,node_api,node_models,node_compat toneAmber
class node_accounts,node_auth,node_config toneMint
class node_agent,node_permissions,node_filetools,node_toolregistry,node_shelltools,node_browsermcp,node_workspace toneRose
class node_arena toneIndigo
```

## Components

### Desktop experience

- [Desktop window](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/desktop.py): `arena/desktop.py`
- [Local web UI](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/web/static/app.js): `arena/web/static/app.js`
- [Flask API](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/web/app.py): `arena/web/app.py`

### Conversation runtime

- [Embedded engine](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/engine.py): `arena/engine.py`
- [Wire contracts](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/contracts.py): `arena/contracts.py`
- [Arena API client](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/api.py): `arena/api.py`
- [Model catalog](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/models.py): `arena/models.py`
- [OpenAI compatibility](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/web/openai_compat.py): `arena/web/openai_compat.py`

### Accounts and state

- [Account management](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/accounts.py): `arena/accounts.py`
- [Authentication](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/auth.py): `arena/auth.py`
- [Settings and storage](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/config.py): `arena/config.py`

### Workspace tools

- [Tool-call agent](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/agent.py): `arena/agent.py`
- [Permission modes](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/permissions.py): `arena/permissions.py`
- [File operations](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/tools/file_tools.py): `arena/tools/file_tools.py`
- [Tool registry](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/tools/__init__.py): `arena/tools/__init__.py`
- [Shell commands](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/tools/shell_tools.py): `arena/tools/shell_tools.py`
- [Browser tools](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/tools/browser_mcp.py): `arena/tools/browser_mcp.py`
- [Code workspace](https://github.com/chaoticmindv/master-v-bates/blob/main/arena/workspace.py): `arena/workspace.py`

### Other components

- **User**
- **Arena.ai**

## Connections

- User → Desktop window: uses (evidence: `README.md`)
- Desktop window → Flask API: starts (evidence: `arena/desktop.py`)
- Desktop window → Embedded engine: hosts (evidence: `arena/desktop.py`)
- User → Local web UI: sends messages (evidence: `README.md`)
- Local web UI → Flask API: requests (evidence: `README.md`)
- Flask API → Embedded engine: dispatches chats (evidence: `arena/web/app.py`)
- Embedded engine → Arena.ai: sends and streams (evidence: `README.md`)
- Flask API → Arena API client: uses client (evidence: `arena/web/app.py`)
- Flask API → Wire contracts: formats requests (evidence: `arena/web/app.py`)
- Embedded engine → Wire contracts: uses formats (evidence: `arena/engine.py`)
- Flask API → Model catalog: loads catalog (evidence: `arena/web/app.py`)
- Flask API → OpenAI compatibility: serves compatibility (evidence: `arena/web/app.py`)
- Flask API → Account management: manages accounts (evidence: `arena/web/app.py`)
- Account management → Authentication: uses authentication (evidence: `arena/accounts.py`)
- Account management → Settings and storage: persists account data (evidence: `arena/accounts.py`)
- Flask API → Settings and storage: reads and writes (evidence: `arena/web/app.py`)
- Flask API → Tool-call agent: runs tool calls (evidence: `arena/web/app.py`)
- Flask API → Permission modes: enforces modes (evidence: `README.md`)
- Tool-call agent → Tool registry: dispatches tools
- Tool registry → File operations: registers (evidence: `arena/tools/__init__.py`)
- Tool registry → Shell commands: registers (evidence: `arena/tools/__init__.py`)
- Tool registry → Browser tools: registers (evidence: `arena/tools/__init__.py`)
- Flask API → Code workspace: copies Code outputs (evidence: `README.md`)
