# czg86389-hub/muse2api architecture

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

- Interactive diagram: https://gitdiagram.com/czg86389-hub/muse2api
- Repository: https://github.com/czg86389-hub/muse2api
- Video tour (about a minute): https://gitdiagram.com/czg86389-hub/muse2api/video

## Overview

MUSE2API exposes Muse.ai chat, image, and video generation through an OpenAI-compatible API. The main workflow is a client request entering the FastAPI application, which selects and renews an account session, drives Muse.ai through isolated Chromium contexts, and returns generated content or a task/media result. The account pool, proxy handling, session/VM maintenance, admin console, and cookie-import tools are supporting product capabilities. Relationships involving unsampled routes are included only where the README documents them; source excerpts are partial.

Main entry points: [`app.py`](https://github.com/czg86389-hub/muse2api/blob/main/app.py) (API Service), [`engine.py`](https://github.com/czg86389-hub/muse2api/blob/main/engine.py) (Muse Engine), [`cdp.py`](https://github.com/czg86389-hub/muse2api/blob/main/cdp.py) (CDP Client), [`proxy.py`](https://github.com/czg86389-hub/muse2api/blob/main/proxy.py) (Proxy Relay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Console"]
  node_app["API Service<br/>[app.py]"]
  node_chat["Chat API<br/>[app.py]"]
  node_images["Image API<br/>[app.py]"]
  node_videos["Video API<br/>[app.py]"]
  node_admin["Admin Console<br/>[admin.html]"]
  node_media["Media Service<br/>[app.py]"]
end

subgraph group_runtime["Generation Runtime"]
  node_engine["Muse Engine<br/>[engine.py]"]
  node_cdp["CDP Client<br/>[cdp.py]"]
  node_proxy["Proxy Relay<br/>[proxy.py]"]
  node_config["Runtime Config<br/>[config.py]"]
end

subgraph group_accounts["Accounts and State"]
  node_accounts_state[("Account Pool<br/>[store.py]")]
  node_tasks_state[("Task State<br/>[store.py]")]
  node_session_ops["Session Maintenance<br/>[app.py]"]
end

subgraph group_import["Account Import"]
  node_extension["Chrome Importer<br/>[popup.js]"]
  node_userscript["Userscript Importer"]
end

node_api_client(("API Client"))
node_browser["Chromium"]
node_muse["Muse.ai"]

node_api_client -->|"sends chat"| node_chat
node_api_client -->|"requests images"| node_images
node_api_client -->|"creates tasks"| node_videos
node_chat -->|"routes through"| node_app
node_images -->|"routes through"| node_app
node_videos -->|"routes through"| node_app
node_app -->|"invokes generation"| node_engine
node_engine -->|"uses protocol"| node_cdp
node_engine -->|"drives contexts"| node_browser
node_cdp -->|"sends commands"| node_browser
node_engine -->|"drives web session"| node_muse
node_app -->|"selects accounts"| node_accounts_state
node_app -->|"records tasks"| node_tasks_state
node_app -->|"binds account proxy"| node_proxy
node_engine -->|"uses account proxy"| node_proxy
node_app -->|"loads settings"| node_config
node_session_ops -->|"renews sessions"| node_engine
node_session_ops -->|"persists account state"| node_accounts_state
node_videos -->|"creates task"| node_tasks_state
node_api_client -->|"fetches media"| node_media
node_admin -->|"uses admin API"| node_app
node_extension -->|"uploads cookies"| node_app
node_userscript -->|"uploads cookies"| node_app

click node_app "https://github.com/czg86389-hub/muse2api/blob/main/app.py"
click node_chat "https://github.com/czg86389-hub/muse2api/blob/main/app.py"
click node_images "https://github.com/czg86389-hub/muse2api/blob/main/app.py"
click node_videos "https://github.com/czg86389-hub/muse2api/blob/main/app.py"
click node_admin "https://github.com/czg86389-hub/muse2api/blob/main/admin.html"
click node_media "https://github.com/czg86389-hub/muse2api/blob/main/app.py"
click node_engine "https://github.com/czg86389-hub/muse2api/blob/main/engine.py"
click node_cdp "https://github.com/czg86389-hub/muse2api/blob/main/cdp.py"
click node_proxy "https://github.com/czg86389-hub/muse2api/blob/main/proxy.py"
click node_config "https://github.com/czg86389-hub/muse2api/blob/main/config.py"
click node_accounts_state "https://github.com/czg86389-hub/muse2api/blob/main/store.py"
click node_tasks_state "https://github.com/czg86389-hub/muse2api/blob/main/store.py"
click node_session_ops "https://github.com/czg86389-hub/muse2api/blob/main/app.py"
click node_extension "https://github.com/czg86389-hub/muse2api/blob/main/extension/popup.js"
click node_userscript "https://github.com/czg86389-hub/muse2api/blob/main/tools/muse2api_cookie_importer.user.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_app,node_chat,node_images,node_videos,node_admin,node_media,node_api_client toneBlue
class node_engine,node_cdp,node_proxy,node_config toneAmber
class node_accounts_state,node_tasks_state,node_session_ops toneMint
class node_extension,node_userscript toneRose
class node_browser,node_muse toneIndigo
```

## Components

### API and Console

- [API Service](https://github.com/czg86389-hub/muse2api/blob/main/app.py): `app.py`
- [Chat API](https://github.com/czg86389-hub/muse2api/blob/main/app.py): `app.py`
- [Image API](https://github.com/czg86389-hub/muse2api/blob/main/app.py): `app.py`
- [Video API](https://github.com/czg86389-hub/muse2api/blob/main/app.py): `app.py`
- [Admin Console](https://github.com/czg86389-hub/muse2api/blob/main/admin.html): `admin.html`
- [Media Service](https://github.com/czg86389-hub/muse2api/blob/main/app.py): `app.py`

### Generation Runtime

- [Muse Engine](https://github.com/czg86389-hub/muse2api/blob/main/engine.py): `engine.py`
- [CDP Client](https://github.com/czg86389-hub/muse2api/blob/main/cdp.py): `cdp.py`
- [Proxy Relay](https://github.com/czg86389-hub/muse2api/blob/main/proxy.py): `proxy.py`
- [Runtime Config](https://github.com/czg86389-hub/muse2api/blob/main/config.py): `config.py`

### Accounts and State

- [Account Pool](https://github.com/czg86389-hub/muse2api/blob/main/store.py): `store.py`
- [Task State](https://github.com/czg86389-hub/muse2api/blob/main/store.py): `store.py`
- [Session Maintenance](https://github.com/czg86389-hub/muse2api/blob/main/app.py): `app.py`

### Account Import

- [Chrome Importer](https://github.com/czg86389-hub/muse2api/blob/main/extension/popup.js): `extension/popup.js`
- [Userscript Importer](https://github.com/czg86389-hub/muse2api/blob/main/tools/muse2api_cookie_importer.user.js): `tools/muse2api_cookie_importer.user.js`

### Other components

- **API Client**
- **Chromium**
- **Muse.ai**

## Connections

- API Client → Chat API: sends chat (evidence: `README.md`)
- API Client → Image API: requests images (evidence: `README.md`)
- API Client → Video API: creates tasks (evidence: `README.md`)
- Chat API → API Service: routes through (evidence: `app.py`)
- Image API → API Service: routes through (evidence: `app.py`)
- Video API → API Service: routes through (evidence: `app.py`)
- API Service → Muse Engine: invokes generation (evidence: `app.py`)
- Muse Engine → CDP Client: uses protocol (evidence: `engine.py`)
- Muse Engine → Chromium: drives contexts (evidence: `README.md`)
- CDP Client → Chromium: sends commands (evidence: `cdp.py`)
- Muse Engine → Muse.ai: drives web session (evidence: `engine.py`)
- API Service → Account Pool: selects accounts (evidence: `app.py`)
- API Service → Task State: records tasks (evidence: `app.py`)
- API Service → Proxy Relay: binds account proxy (evidence: `app.py`)
- Muse Engine → Proxy Relay: uses account proxy (evidence: `engine.py`)
- API Service → Runtime Config: loads settings (evidence: `app.py`)
- Session Maintenance → Muse Engine: renews sessions (evidence: `app.py`)
- Session Maintenance → Account Pool: persists account state (evidence: `app.py`)
- Video API → Task State: creates task (evidence: `app.py`)
- API Client → Media Service: fetches media (evidence: `README.md`)
- Admin Console → API Service: uses admin API (evidence: `README.md`)
- Chrome Importer → API Service: uploads cookies (evidence: `extension/popup.js`)
- Userscript Importer → API Service: uploads cookies (evidence: `tools/muse2api_cookie_importer.user.js`)