# galaxypple072-oss/emilia-companion-desktop architecture

> Architecture diagram of the GitHub repository galaxypple072-oss/emilia-companion-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/galaxypple072-oss/emilia-companion-desktop
- Repository: https://github.com/galaxypple072-oss/emilia-companion-desktop

## Overview

Personal Companion is a multi-channel companion system: users message it through QQ or the desktop pet; Product Core handles conversations and durable outbound work, then routes replies and actions to their destination. The README also documents desktop device capabilities, file/email tools, reminders, encrypted relay workers, and voice synthesis. The excerpts establish selected routing and integration edges; unsampled core internals and feature wiring are represented only where README evidence supports the subsystem, without inferring calls between them.

Main entry points: [`apps/companion-relay/src/server.ts`](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/companion-relay/src/server.ts) (Encrypted Relay), [`apps/product-core/src/runtime.ts`](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/runtime.ts) (Core Runtime), [`apps/product-core/src/agent.ts`](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/agent.ts) (Conversation Agent), [`apps/qq-gateway/src/relay-worker.ts`](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/qq-gateway/src/relay-worker.ts) (QQ Gateway Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Clients"]
  node_desktop["Desktop Companion<br/>[main.js]"]
  node_desktoprelay["Desktop Relay Client<br/>[relay-client.js]"]
end

subgraph group_core["Product Core"]
  node_corecli["Core Runtime<br/>[runtime.ts]"]
  node_agent["Conversation Agent<br/>[agent.ts]"]
  node_turn["Turn Assembly<br/>[turn-assembly.ts]"]
  node_persona["Persona And Policy<br/>[persona.ts]"]
  node_memory["Long-Term Memory<br/>[memory.ts]"]
  node_scheduler["Reply Scheduler<br/>[reply-scheduler.ts]"]
  node_store[("Durable Store<br/>[store.ts]")]
  node_bridge["Companion Bridge"]
  node_deviceapi["Device Control API"]
  node_devicerouter["Device Router"]
end

subgraph group_transport["Transport"]
  node_relay["Encrypted Relay<br/>[server.ts]"]
  node_protocol["Relay Protocol<br/>[index.js]"]
end

subgraph group_integrations["Tools And Services"]
  node_voice["Voice Synthesis<br/>[server.ts]"]
  node_filetools["File Tools<br/>[server.ts]"]
  node_emailtools["Email Tools<br/>[server.ts]"]
  node_devicetools["Device Tools<br/>[server.ts]"]
end

subgraph group_workers["Runtime Workers"]
  node_qqworker["QQ Gateway Worker<br/>[relay-worker.ts]"]
  node_voiceworker["Voice Relay Worker<br/>[relay-worker.ts]"]
end

node_owner(("Owner"))
node_qq(("QQ Account"))
node_onebot["NapCat OneBot"]
node_imap["Email Inbox"]
node_gradio["GPT-SoVITS"]
node_filesystem[("Allowed Local Files")]

node_owner -->|"uses"| node_desktop
node_owner -->|"messages"| node_qq
node_desktop -->|"sends events"| node_desktoprelay
node_desktoprelay -->|"seals payloads"| node_protocol
node_desktoprelay -->|"authenticates"| node_relay
node_relay -->|"routes frames"| node_desktoprelay
node_qq -->|"sends messages"| node_onebot
node_qqworker -->|"uses API"| node_onebot
node_qqworker -->|"seals payloads"| node_protocol
node_qqworker -->|"connects"| node_relay
node_relay -->|"routes frames"| node_qqworker
node_corecli -->|"persists work"| node_store
node_corecli -->|"processes turns"| node_agent
node_agent -->|"assembles context"| node_turn
node_agent -->|"uses persona"| node_persona
node_agent -->|"uses memory"| node_memory
node_agent -->|"reads history"| node_store
node_corecli -->|"schedules delivery"| node_scheduler
node_corecli -->|"serves clients"| node_bridge
node_bridge -->|"dispatches commands"| node_devicerouter
node_devicerouter -->|"serves control"| node_deviceapi
node_corecli -->|"uses transport"| node_relay
node_relay -->|"routes framed data"| node_protocol
node_voiceworker -->|"seals payloads"| node_protocol
node_voiceworker -->|"connects"| node_relay
node_relay -->|"routes frames"| node_voiceworker
node_voiceworker -->|"requests synthesis"| node_voice
node_voice -->|"synthesizes audio"| node_gradio
node_filetools -->|"reads scoped files"| node_filesystem
node_filetools -->|"drafts actions"| node_store
node_emailtools -->|"reads inbox"| node_imap
node_emailtools -->|"drafts actions"| node_store
node_devicetools -->|"calls API"| node_deviceapi

click node_desktop "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/desktop-pet/src/main.js"
click node_desktoprelay "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/desktop-pet/src/relay-client.js"
click node_corecli "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/runtime.ts"
click node_agent "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/agent.ts"
click node_turn "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/turn-assembly.ts"
click node_persona "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/persona.ts"
click node_memory "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/memory.ts"
click node_scheduler "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/reply-scheduler.ts"
click node_store "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/store.ts"
click node_bridge "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/companion-bridge.ts"
click node_deviceapi "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/device-control-api.ts"
click node_devicerouter "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/device-control-router.ts"
click node_relay "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/companion-relay/src/server.ts"
click node_protocol "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/packages/companion-relay-protocol/src/index.js"
click node_qqworker "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/qq-gateway/src/relay-worker.ts"
click node_voiceworker "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/voice-service/src/relay-worker.ts"
click node_voice "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/voice-service/src/server.ts"
click node_filetools "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/file-mcp/src/server.ts"
click node_emailtools "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/email-mcp/src/server.ts"
click node_devicetools "https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/device-mcp/src/server.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_desktop,node_desktoprelay toneBlue
class node_corecli,node_agent,node_turn,node_persona,node_memory,node_scheduler,node_store,node_bridge,node_deviceapi,node_devicerouter,node_filesystem toneAmber
class node_relay,node_protocol toneMint
class node_voice,node_filetools,node_emailtools,node_devicetools toneRose
class node_qqworker,node_voiceworker,node_owner,node_qq,node_onebot,node_imap,node_gradio toneIndigo
```

## Components

### User Clients

- [Desktop Companion](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/desktop-pet/src/main.js): `apps/desktop-pet/src/main.js`
- [Desktop Relay Client](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/desktop-pet/src/relay-client.js): `apps/desktop-pet/src/relay-client.js`

### Product Core

- [Core Runtime](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/runtime.ts): `apps/product-core/src/runtime.ts`
- [Conversation Agent](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/agent.ts): `apps/product-core/src/agent.ts`
- [Turn Assembly](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/turn-assembly.ts): `apps/product-core/src/turn-assembly.ts`
- [Persona And Policy](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/persona.ts): `apps/product-core/src/persona.ts`
- [Long-Term Memory](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/memory.ts): `apps/product-core/src/memory.ts`
- [Reply Scheduler](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/reply-scheduler.ts): `apps/product-core/src/reply-scheduler.ts`
- [Durable Store](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/store.ts): `apps/product-core/src/store.ts`
- [Companion Bridge](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/companion-bridge.ts): `apps/product-core/src/companion-bridge.ts`
- [Device Control API](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/device-control-api.ts): `apps/product-core/src/device-control-api.ts`
- [Device Router](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/product-core/src/device-control-router.ts): `apps/product-core/src/device-control-router.ts`

### Transport

- [Encrypted Relay](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/companion-relay/src/server.ts): `apps/companion-relay/src/server.ts`
- [Relay Protocol](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/packages/companion-relay-protocol/src/index.js): `packages/companion-relay-protocol/src/index.js`

### Tools And Services

- [Voice Synthesis](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/voice-service/src/server.ts): `apps/voice-service/src/server.ts`
- [File Tools](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/file-mcp/src/server.ts): `apps/file-mcp/src/server.ts`
- [Email Tools](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/email-mcp/src/server.ts): `apps/email-mcp/src/server.ts`
- [Device Tools](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/device-mcp/src/server.ts): `apps/device-mcp/src/server.ts`

### Runtime Workers

- [QQ Gateway Worker](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/qq-gateway/src/relay-worker.ts): `apps/qq-gateway/src/relay-worker.ts`
- [Voice Relay Worker](https://github.com/galaxypple072-oss/emilia-companion-desktop/blob/main/apps/voice-service/src/relay-worker.ts): `apps/voice-service/src/relay-worker.ts`

### Other components

- **Owner**
- **QQ Account**
- **NapCat OneBot**
- **Email Inbox**
- **GPT-SoVITS**
- **Allowed Local Files**

## Connections

- Owner → Desktop Companion: uses
- Owner → QQ Account: messages
- Desktop Companion → Desktop Relay Client: sends events
- Desktop Relay Client → Relay Protocol: seals payloads
- Desktop Relay Client → Encrypted Relay: authenticates
- Encrypted Relay → Desktop Relay Client: routes frames
- QQ Account → NapCat OneBot: sends messages
- QQ Gateway Worker → NapCat OneBot: uses API
- QQ Gateway Worker → Relay Protocol: seals payloads
- QQ Gateway Worker → Encrypted Relay: connects
- Encrypted Relay → QQ Gateway Worker: routes frames
- Core Runtime → Durable Store: persists work
- Core Runtime → Conversation Agent: processes turns
- Conversation Agent → Turn Assembly: assembles context
- Conversation Agent → Persona And Policy: uses persona
- Conversation Agent → Long-Term Memory: uses memory
- Conversation Agent → Durable Store: reads history
- Core Runtime → Reply Scheduler: schedules delivery
- Core Runtime → Companion Bridge: serves clients
- Companion Bridge → Device Router: dispatches commands
- Device Router → Device Control API: serves control
- Core Runtime → Encrypted Relay: uses transport
- Encrypted Relay → Relay Protocol: routes framed data
- Voice Relay Worker → Relay Protocol: seals payloads
- Voice Relay Worker → Encrypted Relay: connects
- Encrypted Relay → Voice Relay Worker: routes frames
- Voice Relay Worker → Voice Synthesis: requests synthesis
- Voice Synthesis → GPT-SoVITS: synthesizes audio
- File Tools → Allowed Local Files: reads scoped files
- File Tools → Durable Store: drafts actions
- Email Tools → Email Inbox: reads inbox
- Email Tools → Durable Store: drafts actions
- Device Tools → Device Control API: calls API