# nano-muse/nanomuse architecture

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

- Interactive diagram: https://gitdiagram.com/nano-muse/nanomuse
- Repository: https://github.com/nano-muse/nanomuse

## Overview

nanoMuse is a cross-device personal agent, with phone, desktop, web console, and a relay. The main workflow is that a person sends a request through a client; the always-on runtime manages conversations and delegates work to the agent, tools, or coding service, then streams activity and results back. The repository also includes memory, device coordination, chat-app channels, and account/cloud services. Some client and backend connections are documented only at a high level; those links are marked unverified rather than inferred from names.

Main entry points: [`nanomuse/server/service.py`](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/server/service.py) (Always-on service), [`nanomuse/app.py`](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/app.py) (Runtime composition), [`nanomuse/hub/service.py`](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/hub/service.py) (Device hub), [`android/src/ios/Agent/Chat/ChatStore.swift`](https://github.com/nano-muse/nanomuse/blob/main/android/src/ios/Agent/Chat/ChatStore.swift) (iOS chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_web["Web console<br/>[App.tsx]"]
  node_desktop["Desktop app<br/>[main.ts]"]
  node_ios_chat["iOS chat<br/>[ChatStore.swift]"]
end

subgraph group_runtime["Agent runtime"]
  node_server["Always-on service<br/>[service.py]"]
  node_app["Runtime composition<br/>[app.py]"]
  node_agent["Agent core<br/>[core.py]"]
  node_events["Event bus<br/>[events.py]"]
  node_memory["Memory embeddings<br/>[embeddings.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_coding["Coding service<br/>[service.py]"]
  node_channels["Chat channels<br/>[manager.py]"]
end

subgraph group_coordination["Device coordination"]
  node_hub["Device hub<br/>[service.py]"]
  node_sync["Sync engine<br/>[engine.py]"]
  node_ios_sync["iCloud sync"]
end

subgraph group_services["Cloud services"]
  node_relay["Cloud relay<br/>[service.py]"]
  node_cloud_db[("Relay database<br/>[db.py]")]
end

node_user(("Person"))

node_user -->|"uses"| node_web
node_user -->|"uses"| node_desktop
node_user -->|"uses"| node_ios_chat
node_web -.->|"sends requests"| node_server
node_desktop -.->|"connects to"| node_server
node_ios_chat -.->|"shares conversations"| node_server
node_server -->|"owns runtime"| node_app
node_app -.->|"composes agent"| node_agent
node_server -->|"publishes events"| node_events
node_server -->|"uses service"| node_coding
node_server -->|"uses service"| node_hub
node_server -->|"routes chat"| node_channels
node_channels -->|"runs requests"| node_server
node_app -->|"configures memory"| node_memory
node_hub -->|"coordinates sync"| node_sync
node_sync -->|"publishes updates"| node_server
node_ios_sync -->|"reads and updates"| node_ios_chat
node_hub -.->|"uses account relay"| node_relay
node_relay -->|"uses database"| node_cloud_db

click node_web "https://github.com/nano-muse/nanomuse/blob/main/web/src/App.tsx"
click node_desktop "https://github.com/nano-muse/nanomuse/blob/main/harness/desktop/src/main.ts"
click node_ios_chat "https://github.com/nano-muse/nanomuse/blob/main/android/src/ios/Agent/Chat/ChatStore.swift"
click node_server "https://github.com/nano-muse/nanomuse/blob/main/nanomuse/server/service.py"
click node_app "https://github.com/nano-muse/nanomuse/blob/main/nanomuse/app.py"
click node_agent "https://github.com/nano-muse/nanomuse/blob/main/nanomuse/agent/core.py"
click node_events "https://github.com/nano-muse/nanomuse/blob/main/nanomuse/server/events.py"
click node_memory "https://github.com/nano-muse/nanomuse/blob/main/nanomuse/memory/embeddings.py"
click node_coding "https://github.com/nano-muse/nanomuse/blob/main/nanomuse/coding/service.py"
click node_channels "https://github.com/nano-muse/nanomuse/blob/main/nanomuse/channels/manager.py"
click node_hub "https://github.com/nano-muse/nanomuse/blob/main/nanomuse/hub/service.py"
click node_sync "https://github.com/nano-muse/nanomuse/blob/main/nanomuse/sync/engine.py"
click node_ios_sync "https://github.com/nano-muse/nanomuse/blob/main/android/src/ios/Agent/Sync/CloudSyncEngine.swift"
click node_relay "https://github.com/nano-muse/nanomuse/blob/main/cloud/nanomuse_cloud/service.py"
click node_cloud_db "https://github.com/nano-muse/nanomuse/blob/main/cloud/nanomuse_cloud/db.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_web,node_desktop,node_ios_chat toneBlue
class node_server,node_app,node_agent,node_events,node_memory toneAmber
class node_coding,node_channels toneMint
class node_hub,node_sync,node_ios_sync toneRose
class node_relay,node_cloud_db,node_user toneIndigo
```

## Components

### User clients

- [Web console](https://github.com/nano-muse/nanomuse/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Desktop app](https://github.com/nano-muse/nanomuse/blob/main/harness/desktop/src/main.ts): `harness/desktop/src/main.ts`
- [iOS chat](https://github.com/nano-muse/nanomuse/blob/main/android/src/ios/Agent/Chat/ChatStore.swift): `android/src/ios/Agent/Chat/ChatStore.swift`

### Agent runtime

- [Always-on service](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/server/service.py): `nanomuse/server/service.py`
- [Runtime composition](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/app.py): `nanomuse/app.py`
- [Agent core](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/agent/core.py): `nanomuse/agent/core.py`
- [Event bus](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/server/events.py): `nanomuse/server/events.py`
- [Memory embeddings](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/memory/embeddings.py): `nanomuse/memory/embeddings.py`

### Agent capabilities

- [Coding service](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/coding/service.py): `nanomuse/coding/service.py`
- [Chat channels](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/channels/manager.py): `nanomuse/channels/manager.py`

### Device coordination

- [Device hub](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/hub/service.py): `nanomuse/hub/service.py`
- [Sync engine](https://github.com/nano-muse/nanomuse/blob/main/nanomuse/sync/engine.py): `nanomuse/sync/engine.py`
- [iCloud sync](https://github.com/nano-muse/nanomuse/blob/main/android/src/ios/Agent/Sync/CloudSyncEngine.swift): `android/src/ios/Agent/Sync/CloudSyncEngine.swift`

### Cloud services

- [Cloud relay](https://github.com/nano-muse/nanomuse/blob/main/cloud/nanomuse_cloud/service.py): `cloud/nanomuse_cloud/service.py`
- [Relay database](https://github.com/nano-muse/nanomuse/blob/main/cloud/nanomuse_cloud/db.py): `cloud/nanomuse_cloud/db.py`

### Other components

- **Person**

## Connections

- Person → Web console: uses (evidence: `README.md`)
- Person → Desktop app: uses (evidence: `README.md`)
- Person → iOS chat: uses (evidence: `README.md`)
- Web console → Always-on service: sends requests
- Desktop app → Always-on service: connects to
- iOS chat → Always-on service: shares conversations (evidence: `README.md`)
- Always-on service → Runtime composition: owns runtime (evidence: `nanomuse/server/service.py`)
- Runtime composition → Agent core: composes agent
- Always-on service → Event bus: publishes events (evidence: `nanomuse/server/service.py`)
- Always-on service → Coding service: uses service (evidence: `nanomuse/server/service.py`)
- Always-on service → Device hub: uses service (evidence: `nanomuse/server/service.py`)
- Always-on service → Chat channels: routes chat (evidence: `nanomuse/channels/manager.py`)
- Chat channels → Always-on service: runs requests (evidence: `nanomuse/channels/manager.py`)
- Runtime composition → Memory embeddings: configures memory (evidence: `nanomuse/app.py`)
- Device hub → Sync engine: coordinates sync (evidence: `nanomuse/hub/service.py`)
- Sync engine → Always-on service: publishes updates (evidence: `nanomuse/sync/engine.py`)
- iCloud sync → iOS chat: reads and updates (evidence: `android/src/ios/Agent/Sync/CloudSyncEngine.swift`)
- Device hub → Cloud relay: uses account relay
- Cloud relay → Relay database: uses database (evidence: `cloud/nanomuse_cloud/service.py`)