# sqfcyily/deva architecture

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

- Interactive diagram: https://gitdiagram.com/sqfcyily/deva
- Repository: https://github.com/sqfcyily/deva

## Overview

Deva is a local-first desktop AI agent: users work through chat, where the main role can use tools, coordinate members or subagents, and return deliverables. The desktop renderer communicates through the preload boundary with main-process services; local conversation state and scheduled tasks are persisted separately. Documented branches include model providers, browser and workspace tools, memory, skills/MCP, Git, and remote phone access through Feishu or Telegram. The README supports the product workflow; unsampled implementations are represented by their listed paths, and uncertain wiring is omitted.

Main entry points: [`apps/desktop/src/main/services/agent-loop.ts`](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/agent-loop.ts) (Agent loop), [`apps/desktop/src/renderer/src/store/chat.tsx`](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/renderer/src/store/chat.tsx) (Chat state), [`apps/desktop/src/main/services/chat.ts`](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/chat.ts) (Chat service), [`apps/desktop/src/main/services/chat-store.ts`](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/chat-store.ts) (Conversation store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop experience"]
  node_chat_ui["Chat interface<br/>[Conversation.tsx]"]
  node_chat_store["Chat state<br/>[chat.tsx]"]
  node_preload["IPC bridge<br/>[index.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_main["Main process<br/>[index.ts]"]
  node_chat_service["Chat service<br/>[chat.ts]"]
  node_agent_loop["Agent loop<br/>[agent-loop.ts]"]
  node_provider["Model providers<br/>[provider.ts]"]
  node_subagents["Subagents<br/>[subagents.ts]"]
  node_members["Team members<br/>[members.ts]"]
end

subgraph group_state["Local state"]
  node_chat_files[("Conversation store<br/>[chat-store.ts]")]
  node_checkpoints[("Checkpoints<br/>[checkpoints.ts]")]
  node_config[("Configuration<br/>[config.ts]")]
  node_tasks[("Scheduled tasks<br/>[tasks.ts]")]
end

subgraph group_capabilities["Agent capabilities"]
  node_workspace["Workspace tools<br/>[workspace.ts]"]
  node_browser["Built-in browser<br/>[host.ts]"]
  node_skills_mcp["Skills and MCP<br/>[skills.ts]"]
  node_memory["Memory<br/>[memory.ts]"]
  node_git["Git operations<br/>[git.ts]"]
end

subgraph group_remote["Remote access"]
  node_remote_ui["Mobile client<br/>[App.tsx]"]
  node_remote_server["Remote server<br/>[server.ts]"]
  node_remote_protocol["Remote protocol<br/>[remote-web.ts]"]
  node_relay["Relay service<br/>[relay.ts]"]
  node_feishu["Feishu / Telegram<br/>[hub.ts]"]
end

node_user(("User"))

node_user -->|"requests work"| node_chat_ui
node_chat_ui -->|"sends messages"| node_chat_store
node_chat_store -->|"invokes chat API"| node_preload
node_main -->|"registers service"| node_chat_service
node_chat_service -.->|"loads conversations"| node_chat_files
node_chat_service -.->|"starts agent run"| node_agent_loop
node_agent_loop -.->|"requests model output"| node_provider
node_agent_loop -.->|"delegates subtasks"| node_subagents
node_agent_loop -.->|"coordinates members"| node_members
node_agent_loop -.->|"uses tools"| node_workspace
node_agent_loop -.->|"uses browser"| node_browser
node_agent_loop -.->|"uses extensions"| node_skills_mcp
node_agent_loop -.->|"uses memory"| node_memory
node_agent_loop -.->|"uses Git tools"| node_git
node_chat_service -.->|"supports rewind"| node_checkpoints
node_tasks -->|"binds task sessions"| node_chat_files
node_user -->|"continues on phone"| node_remote_ui
node_remote_ui -->|"exchanges frames"| node_remote_protocol
node_remote_server -->|"implements protocol"| node_remote_protocol
node_remote_server -.->|"serves chat history"| node_chat_files
node_user -->|"messages remotely"| node_feishu
node_user -.->|"connects remotely"| node_relay
node_chat_store -->|"mirrors task state"| node_tasks
node_chat_store -->|"reads preferences"| node_config

click node_chat_ui "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/renderer/src/redesign/Conversation.tsx"
click node_chat_store "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/renderer/src/store/chat.tsx"
click node_preload "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/preload/index.ts"
click node_main "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/index.ts"
click node_chat_service "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/chat.ts"
click node_agent_loop "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/agent-loop.ts"
click node_provider "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/provider.ts"
click node_subagents "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/subagents.ts"
click node_members "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/members.ts"
click node_chat_files "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/chat-store.ts"
click node_checkpoints "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/checkpoints.ts"
click node_config "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/config.ts"
click node_tasks "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/tasks.ts"
click node_workspace "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/workspace.ts"
click node_browser "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/browser/host.ts"
click node_skills_mcp "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/skills.ts"
click node_memory "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/memory.ts"
click node_git "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/git.ts"
click node_remote_ui "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/mobile/App.tsx"
click node_remote_server "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/remote/web/server.ts"
click node_remote_protocol "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/shared/remote-web.ts"
click node_relay "https://github.com/sqfcyily/deva/blob/main/apps/relay-node/src/relay.ts"
click node_feishu "https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/remote/hub.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_chat_ui,node_chat_store,node_preload,node_user toneBlue
class node_main,node_chat_service,node_agent_loop,node_provider,node_subagents,node_members toneAmber
class node_chat_files,node_checkpoints,node_config,node_tasks toneMint
class node_workspace,node_browser,node_skills_mcp,node_memory,node_git toneRose
class node_remote_ui,node_remote_server,node_remote_protocol,node_relay,node_feishu toneIndigo
```

## Components

### Desktop experience

- [Chat interface](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/renderer/src/redesign/Conversation.tsx): `apps/desktop/src/renderer/src/redesign/Conversation.tsx`
- [Chat state](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/renderer/src/store/chat.tsx): `apps/desktop/src/renderer/src/store/chat.tsx`
- [IPC bridge](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/preload/index.ts): `apps/desktop/src/preload/index.ts`

### Agent runtime

- [Main process](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/index.ts): `apps/desktop/src/main/index.ts`
- [Chat service](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/chat.ts): `apps/desktop/src/main/services/chat.ts`
- [Agent loop](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/agent-loop.ts): `apps/desktop/src/main/services/agent-loop.ts`
- [Model providers](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/provider.ts): `apps/desktop/src/main/services/provider.ts`
- [Subagents](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/subagents.ts): `apps/desktop/src/main/services/subagents.ts`
- [Team members](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/members.ts): `apps/desktop/src/main/services/members.ts`

### Local state

- [Conversation store](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/chat-store.ts): `apps/desktop/src/main/services/chat-store.ts`
- [Checkpoints](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/checkpoints.ts): `apps/desktop/src/main/services/checkpoints.ts`
- [Configuration](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/config.ts): `apps/desktop/src/main/services/config.ts`
- [Scheduled tasks](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/tasks.ts): `apps/desktop/src/main/services/tasks.ts`

### Agent capabilities

- [Workspace tools](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/workspace.ts): `apps/desktop/src/main/services/workspace.ts`
- [Built-in browser](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/browser/host.ts): `apps/desktop/src/main/services/browser/host.ts`
- [Skills and MCP](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/skills.ts): `apps/desktop/src/main/services/skills.ts`
- [Memory](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/memory.ts): `apps/desktop/src/main/services/memory.ts`
- [Git operations](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/git.ts): `apps/desktop/src/main/services/git.ts`

### Remote access

- [Mobile client](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/mobile/App.tsx): `apps/desktop/src/mobile/App.tsx`
- [Remote server](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/remote/web/server.ts): `apps/desktop/src/main/services/remote/web/server.ts`
- [Remote protocol](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/shared/remote-web.ts): `apps/desktop/src/shared/remote-web.ts`
- [Relay service](https://github.com/sqfcyily/deva/blob/main/apps/relay-node/src/relay.ts): `apps/relay-node/src/relay.ts`
- [Feishu / Telegram](https://github.com/sqfcyily/deva/blob/main/apps/desktop/src/main/services/remote/hub.ts): `apps/desktop/src/main/services/remote/hub.ts`

### Other components

- **User**

## Connections

- User → Chat interface: requests work (evidence: `README.md`)
- Chat interface → Chat state: sends messages
- Chat state → IPC bridge: invokes chat API (evidence: `apps/desktop/src/renderer/src/store/chat.tsx`)
- Main process → Chat service: registers service (evidence: `apps/desktop/src/main/index.ts`)
- Chat service → Conversation store: loads conversations
- Chat service → Agent loop: starts agent run
- Agent loop → Model providers: requests model output
- Agent loop → Subagents: delegates subtasks
- Agent loop → Team members: coordinates members
- Agent loop → Workspace tools: uses tools
- Agent loop → Built-in browser: uses browser
- Agent loop → Skills and MCP: uses extensions
- Agent loop → Memory: uses memory
- Agent loop → Git operations: uses Git tools
- Chat service → Checkpoints: supports rewind
- Scheduled tasks → Conversation store: binds task sessions (evidence: `apps/desktop/src/main/services/chat-store.ts`)
- User → Mobile client: continues on phone (evidence: `README.md`)
- Mobile client → Remote protocol: exchanges frames (evidence: `apps/desktop/src/mobile/App.tsx`)
- Remote server → Remote protocol: implements protocol (evidence: `apps/desktop/src/main/services/remote/web/server.ts`)
- Remote server → Conversation store: serves chat history
- User → Feishu / Telegram: messages remotely (evidence: `README.md`)
- User → Relay service: connects remotely
- Chat state → Scheduled tasks: mirrors task state
- Chat state → Configuration: reads preferences
