# andrew-babo/muse4ai architecture

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

- Interactive diagram: https://gitdiagram.com/andrew-babo/muse4ai
- Repository: https://github.com/andrew-babo/muse4ai

## Overview

Muse4AI is a Windows desktop bridge that lets a person use Muse interactively or let an external agent submit and manage image, video, chat, and extension jobs through a local API. The API server routes REST/MCP and OAuth requests into job services; the coordinator manages execution, while the repository and database retain jobs and assets. The desktop renderer provides the local control surface. The README also documents a shared bilingual guide, agent instructions, and use-case content. Some execution and storage wiring is only partly sampled, so uncertain links are omitted or marked unverified.

Main entry points: [`desktop/src/main/coordinator.ts`](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/coordinator.ts) (Job coordinator), [`desktop/src/main/repo.ts`](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/repo.ts) (Domain repository), [`desktop/src/main/api/service.ts`](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/service.ts) (Job API service), [`desktop/src/main/ipcHandlers.ts`](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/ipcHandlers.ts) (IPC handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_renderer["Desktop UI<br/>[App.tsx]"]
  node_main["Main process<br/>[main.ts]"]
  node_ipc["IPC handlers<br/>[ipcHandlers.ts]"]
end

subgraph group_agent_api["Agent API"]
  node_api_server["API server<br/>[server.ts]"]
  node_api_controller["API controller<br/>[controller.ts]"]
  node_api_service["Job API service<br/>[service.ts]"]
  node_oauth_http["OAuth routes<br/>[http.ts]"]
  node_oauth_service["OAuth service<br/>[service.ts]"]
end

subgraph group_execution["Job execution"]
  node_coordinator["Job coordinator<br/>[coordinator.ts]"]
  node_adapters["Muse adapters"]
  node_vibes["Vibes integration"]
  node_services["Desktop services<br/>[services.ts]"]
end

subgraph group_persistence["Local data"]
  node_repo["Domain repository<br/>[repo.ts]"]
  node_database[("SQLite database<br/>[db.ts]")]
  node_api_store["API key store<br/>[store.ts]"]
  node_media["Media handling<br/>[media.ts]"]
end

subgraph group_shared_content["Shared content"]
  node_guide_content["Guide content<br/>[chapters.ts]"]
  node_agent_content["Agent instructions<br/>[agents.ts]"]
  node_usecases["Use cases<br/>[usecases.ts]"]
  node_content_routes["Content routes<br/>[routes.ts]"]
end

node_user(("Person"))
node_agents(("AI agents"))
node_muse(("Muse session"))

node_user -->|"uses"| node_renderer
node_agents -->|"requests jobs"| node_api_server
node_api_server -->|"routes requests"| node_api_service
node_api_server -->|"dispatches OAuth"| node_oauth_http
node_oauth_http -->|"handles protocol"| node_oauth_service
node_api_controller -->|"configures"| node_oauth_service
node_api_service -->|"submits jobs"| node_coordinator
node_api_service -->|"reads assets"| node_repo
node_api_service -.->|"checks keys"| node_api_store
node_renderer -.->|"invokes commands"| node_ipc
node_main -->|"registers handlers"| node_ipc
node_main -->|"creates controller"| node_api_controller
node_main -.->|"starts runtime"| node_coordinator
node_ipc -->|"dispatches commands"| node_coordinator
node_ipc -->|"dispatches services"| node_services
node_services -->|"manages batches"| node_coordinator
node_services -->|"reads and writes"| node_repo
node_coordinator -->|"persists job state"| node_repo
node_repo -->|"queries"| node_database
node_coordinator -.->|"executes jobs"| node_adapters
node_adapters -->|"uses signed-in session"| node_muse
node_coordinator -.->|"supports integration"| node_vibes
node_repo -.->|"stores asset records"| node_media
node_content_routes -->|"routes content"| node_guide_content
node_content_routes -->|"routes content"| node_agent_content
node_content_routes -->|"routes content"| node_usecases

click node_renderer "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/renderer/App.tsx"
click node_main "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/main.ts"
click node_ipc "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/ipcHandlers.ts"
click node_api_server "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/server.ts"
click node_api_controller "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/controller.ts"
click node_api_service "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/service.ts"
click node_oauth_http "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/oauth/http.ts"
click node_oauth_service "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/oauth/service.ts"
click node_coordinator "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/coordinator.ts"
click node_adapters "https://github.com/andrew-babo/muse4ai/tree/main/desktop/src/main/adapter"
click node_vibes "https://github.com/andrew-babo/muse4ai/tree/main/desktop/src/main/adapter/vibes"
click node_services "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/services.ts"
click node_repo "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/repo.ts"
click node_database "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/db.ts"
click node_api_store "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/store.ts"
click node_media "https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/media.ts"
click node_guide_content "https://github.com/andrew-babo/muse4ai/blob/main/content/chapters.ts"
click node_agent_content "https://github.com/andrew-babo/muse4ai/blob/main/content/agents/agents.ts"
click node_usecases "https://github.com/andrew-babo/muse4ai/blob/main/content/usecases/usecases.ts"
click node_content_routes "https://github.com/andrew-babo/muse4ai/blob/main/content/routes.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_renderer,node_main,node_ipc toneBlue
class node_api_server,node_api_controller,node_api_service,node_oauth_http,node_oauth_service toneAmber
class node_coordinator,node_adapters,node_vibes,node_services toneMint
class node_repo,node_database,node_api_store,node_media toneRose
class node_guide_content,node_agent_content,node_usecases,node_content_routes,node_user,node_agents,node_muse toneIndigo
```

## Components

### Desktop app

- [Desktop UI](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/renderer/App.tsx): `desktop/src/renderer/App.tsx`
- [Main process](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/main.ts): `desktop/src/main/main.ts`
- [IPC handlers](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/ipcHandlers.ts): `desktop/src/main/ipcHandlers.ts`

### Agent API

- [API server](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/server.ts): `desktop/src/main/api/server.ts`
- [API controller](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/controller.ts): `desktop/src/main/api/controller.ts`
- [Job API service](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/service.ts): `desktop/src/main/api/service.ts`
- [OAuth routes](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/oauth/http.ts): `desktop/src/main/api/oauth/http.ts`
- [OAuth service](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/oauth/service.ts): `desktop/src/main/api/oauth/service.ts`

### Job execution

- [Job coordinator](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/coordinator.ts): `desktop/src/main/coordinator.ts`
- [Muse adapters](https://github.com/andrew-babo/muse4ai/tree/main/desktop/src/main/adapter): `desktop/src/main/adapter`
- [Vibes integration](https://github.com/andrew-babo/muse4ai/tree/main/desktop/src/main/adapter/vibes): `desktop/src/main/adapter/vibes`
- [Desktop services](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/services.ts): `desktop/src/main/services.ts`

### Local data

- [Domain repository](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/repo.ts): `desktop/src/main/repo.ts`
- [SQLite database](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/db.ts): `desktop/src/main/db.ts`
- [API key store](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/api/store.ts): `desktop/src/main/api/store.ts`
- [Media handling](https://github.com/andrew-babo/muse4ai/blob/main/desktop/src/main/media.ts): `desktop/src/main/media.ts`

### Shared content

- [Guide content](https://github.com/andrew-babo/muse4ai/blob/main/content/chapters.ts): `content/chapters.ts`
- [Agent instructions](https://github.com/andrew-babo/muse4ai/blob/main/content/agents/agents.ts): `content/agents/agents.ts`
- [Use cases](https://github.com/andrew-babo/muse4ai/blob/main/content/usecases/usecases.ts): `content/usecases/usecases.ts`
- [Content routes](https://github.com/andrew-babo/muse4ai/blob/main/content/routes.ts): `content/routes.ts`

### Other components

- **Person**
- **AI agents**
- **Muse session**

## Connections

- Person → Desktop UI: uses (evidence: `README.md`)
- AI agents → API server: requests jobs (evidence: `README.md`)
- API server → Job API service: routes requests (evidence: `desktop/src/main/api/server.ts`)
- API server → OAuth routes: dispatches OAuth (evidence: `desktop/src/main/api/server.ts`)
- OAuth routes → OAuth service: handles protocol (evidence: `desktop/src/main/api/oauth/http.ts`)
- API controller → OAuth service: configures (evidence: `desktop/src/main/api/controller.ts`)
- Job API service → Job coordinator: submits jobs (evidence: `desktop/src/main/api/service.ts`)
- Job API service → Domain repository: reads assets (evidence: `desktop/src/main/api/service.ts`)
- Job API service → API key store: checks keys (evidence: `desktop/src/main/api/service.ts`)
- Desktop UI → IPC handlers: invokes commands
- Main process → IPC handlers: registers handlers (evidence: `desktop/src/main/main.ts`)
- Main process → API controller: creates controller (evidence: `desktop/src/main/main.ts`)
- Main process → Job coordinator: starts runtime (evidence: `desktop/src/main/main.ts`)
- IPC handlers → Job coordinator: dispatches commands (evidence: `desktop/src/main/ipcHandlers.ts`)
- IPC handlers → Desktop services: dispatches services (evidence: `desktop/src/main/ipcHandlers.ts`)
- Desktop services → Job coordinator: manages batches (evidence: `desktop/src/main/services.ts`)
- Desktop services → Domain repository: reads and writes (evidence: `desktop/src/main/services.ts`)
- Job coordinator → Domain repository: persists job state (evidence: `desktop/src/main/coordinator.ts`)
- Domain repository → SQLite database: queries (evidence: `desktop/src/main/repo.ts`)
- Job coordinator → Muse adapters: executes jobs (evidence: `desktop/src/main/coordinator.ts`)
- Muse adapters → Muse session: uses signed-in session (evidence: `README.md`)
- Job coordinator → Vibes integration: supports integration
- Domain repository → Media handling: stores asset records
- Content routes → Guide content: routes content (evidence: `content/routes.ts`)
- Content routes → Agent instructions: routes content (evidence: `content/routes.ts`)
- Content routes → Use cases: routes content (evidence: `content/routes.ts`)