# feder-cr/dots architecture

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

- Interactive diagram: https://gitdiagram.com/feder-cr/dots
- Repository: https://github.com/feder-cr/dots

## Overview

invisible_dots runs persistent AI agents, each with its own QEMU computer, on the user's PC. The main workflow is a message or scheduled task arriving through a web, CLI, API, or channel interface; the host API and scheduler coordinate durable state and VM lifecycle; the guest engine reasons with a model, applies permission gates, and uses computer, file, and browser tools; results return as messages and events. The README documents several interfaces and capabilities not fully represented in sampled source, so those branches are shown at subsystem-directory level; links without direct source evidence are omitted.

Main entry points: [`invisible_engine_dots/nanobot/dots/engine.py`](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/engine.py) (Agent engine), [`apps/api/src/server.ts`](https://github.com/feder-cr/dots/blob/main/apps/api/src/server.ts) (HTTP API), [`packages/channels/src`](https://github.com/feder-cr/dots/tree/main/packages/channels/src) (Channel adapters), [`apps/scheduler/src`](https://github.com/feder-cr/dots/tree/main/apps/scheduler/src) (Scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["Web UI"]
  node_cli["CLI"]
end

subgraph group_host["Host control plane"]
  node_api["HTTP API<br/>[server.ts]"]
  node_scheduler["Scheduler"]
  node_hostdb[("Host database<br/>[database.ts]")]
  node_events["Event stream<br/>[event-log.ts]"]
end

subgraph group_guest["Guest agent"]
  node_agentd["Guest relay<br/>[main.go]"]
  node_guestapi["Guest API<br/>[server.py]"]
  node_engine["Agent engine<br/>[engine.py]"]
  node_permissions["Permission gates<br/>[permissions.py]"]
  node_provider["Model provider<br/>[provider.py]"]
  node_providerimpl["OpenAI-compatible"]
  node_gueststore[("Guest state store<br/>[store.py]")]
  node_computer["Computer control<br/>[computer.py]"]
  node_browser["Browser identities<br/>[browser.py]"]
  node_tools["Agent tools"]
  node_cron["Guest automations<br/>[service.py]"]
end

subgraph group_runtime["Computer runtime"]
  node_vmmanager["VM manager<br/>[vm-manager.ts]"]
  node_guestclient["Guest client<br/>[guest-client.ts]"]
  node_qemu["QEMU VM"]
end

subgraph group_channels["Messaging channels"]
  node_channels["Channel adapters"]
end

node_user(("User"))
node_model["OpenRouter model"]
node_weboutside["Websites"]
node_telegram["Telegram"]
node_whatsapp["WhatsApp"]

node_user -->|"uses"| node_web
node_user -->|"uses"| node_cli
node_user -->|"uses"| node_api
node_user -->|"messages"| node_channels
node_web -->|"requests"| node_api
node_cli -->|"requests"| node_api
node_channels -->|"delivers messages"| node_api
node_api -->|"routes work"| node_scheduler
node_api -->|"configures"| node_hostdb
node_api -->|"streams events"| node_events
node_scheduler -->|"persists state"| node_hostdb
node_scheduler -->|"controls lifecycle"| node_vmmanager
node_vmmanager -->|"starts VM"| node_qemu
node_vmmanager -->|"creates client"| node_guestclient
node_guestclient -->|"calls guest"| node_agentd
node_agentd -->|"relays requests"| node_guestapi
node_guestapi -->|"serves engine"| node_engine
node_engine -->|"reads and writes"| node_gueststore
node_engine -->|"requests completion"| node_provider
node_provider -->|"selects provider"| node_providerimpl
node_providerimpl -->|"sends prompts"| node_model
node_engine -->|"checks actions"| node_permissions
node_engine -->|"dispatches tools"| node_tools
node_tools -.->|"controls computer"| node_computer
node_engine -->|"uses identities"| node_browser
node_browser -->|"browses"| node_weboutside
node_engine -.->|"runs automations"| node_cron
node_channels -->|"connects"| node_telegram
node_channels -.->|"connects"| node_whatsapp

click node_web "https://github.com/feder-cr/dots/tree/main/apps/web/src/components"
click node_cli "https://github.com/feder-cr/dots/tree/main/apps/cli/src"
click node_api "https://github.com/feder-cr/dots/blob/main/apps/api/src/server.ts"
click node_scheduler "https://github.com/feder-cr/dots/tree/main/apps/scheduler/src"
click node_hostdb "https://github.com/feder-cr/dots/blob/main/packages/database/src/database.ts"
click node_events "https://github.com/feder-cr/dots/blob/main/packages/events/src/event-log.ts"
click node_vmmanager "https://github.com/feder-cr/dots/blob/main/apps/vm-manager/src/vm-manager.ts"
click node_guestclient "https://github.com/feder-cr/dots/blob/main/apps/vm-manager/src/guest-client.ts"
click node_agentd "https://github.com/feder-cr/dots/blob/main/guest/dot-agentd/cmd/dot-agentd/main.go"
click node_guestapi "https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/server.py"
click node_engine "https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/engine.py"
click node_permissions "https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/permissions.py"
click node_provider "https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/provider.py"
click node_providerimpl "https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/providers/openai_compat_provider.py"
click node_gueststore "https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/store.py"
click node_computer "https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/computer.py"
click node_browser "https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/browser.py"
click node_tools "https://github.com/feder-cr/dots/tree/main/invisible_engine_dots/nanobot/agent/tools"
click node_cron "https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/cron/service.py"
click node_channels "https://github.com/feder-cr/dots/tree/main/packages/channels/src"

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_cli,node_user toneBlue
class node_api,node_scheduler,node_hostdb,node_events toneAmber
class node_agentd,node_guestapi,node_engine,node_permissions,node_provider,node_providerimpl,node_gueststore,node_computer,node_browser,node_tools,node_cron,node_model toneMint
class node_vmmanager,node_guestclient,node_qemu toneRose
class node_channels,node_weboutside,node_telegram,node_whatsapp toneIndigo
```

## Components

### User interfaces

- [Web UI](https://github.com/feder-cr/dots/tree/main/apps/web/src/components): `apps/web/src/components`
- [CLI](https://github.com/feder-cr/dots/tree/main/apps/cli/src): `apps/cli/src`

### Host control plane

- [HTTP API](https://github.com/feder-cr/dots/blob/main/apps/api/src/server.ts): `apps/api/src/server.ts`
- [Scheduler](https://github.com/feder-cr/dots/tree/main/apps/scheduler/src): `apps/scheduler/src`
- [Host database](https://github.com/feder-cr/dots/blob/main/packages/database/src/database.ts): `packages/database/src/database.ts`
- [Event stream](https://github.com/feder-cr/dots/blob/main/packages/events/src/event-log.ts): `packages/events/src/event-log.ts`

### Guest agent

- [Guest relay](https://github.com/feder-cr/dots/blob/main/guest/dot-agentd/cmd/dot-agentd/main.go): `guest/dot-agentd/cmd/dot-agentd/main.go`
- [Guest API](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/server.py): `invisible_engine_dots/nanobot/dots/server.py`
- [Agent engine](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/engine.py): `invisible_engine_dots/nanobot/dots/engine.py`
- [Permission gates](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/permissions.py): `invisible_engine_dots/nanobot/dots/permissions.py`
- [Model provider](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/provider.py): `invisible_engine_dots/nanobot/dots/provider.py`
- [OpenAI-compatible](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/providers/openai_compat_provider.py): `invisible_engine_dots/nanobot/providers/openai_compat_provider.py`
- [Guest state store](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/store.py): `invisible_engine_dots/nanobot/dots/store.py`
- [Computer control](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/computer.py): `invisible_engine_dots/nanobot/dots/computer.py`
- [Browser identities](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/dots/browser.py): `invisible_engine_dots/nanobot/dots/browser.py`
- [Agent tools](https://github.com/feder-cr/dots/tree/main/invisible_engine_dots/nanobot/agent/tools): `invisible_engine_dots/nanobot/agent/tools`
- [Guest automations](https://github.com/feder-cr/dots/blob/main/invisible_engine_dots/nanobot/cron/service.py): `invisible_engine_dots/nanobot/cron/service.py`

### Computer runtime

- [VM manager](https://github.com/feder-cr/dots/blob/main/apps/vm-manager/src/vm-manager.ts): `apps/vm-manager/src/vm-manager.ts`
- [Guest client](https://github.com/feder-cr/dots/blob/main/apps/vm-manager/src/guest-client.ts): `apps/vm-manager/src/guest-client.ts`
- **QEMU VM**

### Messaging channels

- [Channel adapters](https://github.com/feder-cr/dots/tree/main/packages/channels/src): `packages/channels/src`

### Other components

- **User**
- **OpenRouter model**
- **Websites**
- **Telegram**
- **WhatsApp**

## Connections

- User → Web UI: uses
- User → CLI: uses
- User → HTTP API: uses
- User → Channel adapters: messages
- Web UI → HTTP API: requests
- CLI → HTTP API: requests (evidence: `apps/cli/src/api-client.ts`)
- Channel adapters → HTTP API: delivers messages
- HTTP API → Scheduler: routes work (evidence: `apps/api/src/server.ts`)
- HTTP API → Host database: configures
- HTTP API → Event stream: streams events (evidence: `apps/api/src/server.ts`)
- Scheduler → Host database: persists state
- Scheduler → VM manager: controls lifecycle
- VM manager → QEMU VM: starts VM
- VM manager → Guest client: creates client (evidence: `apps/vm-manager/src/vm-manager.ts`)
- Guest client → Guest relay: calls guest (evidence: `apps/vm-manager/src/guest-client.ts`)
- Guest relay → Guest API: relays requests (evidence: `guest/dot-agentd/cmd/dot-agentd/main.go`)
- Guest API → Agent engine: serves engine (evidence: `invisible_engine_dots/nanobot/dots/server.py`)
- Agent engine → Guest state store: reads and writes (evidence: `invisible_engine_dots/nanobot/dots/engine.py`)
- Agent engine → Model provider: requests completion (evidence: `invisible_engine_dots/nanobot/dots/engine.py`)
- Model provider → OpenAI-compatible: selects provider (evidence: `invisible_engine_dots/nanobot/dots/provider.py`)
- OpenAI-compatible → OpenRouter model: sends prompts
- Agent engine → Permission gates: checks actions (evidence: `invisible_engine_dots/nanobot/dots/engine.py`)
- Agent engine → Agent tools: dispatches tools (evidence: `invisible_engine_dots/nanobot/dots/engine.py`)
- Agent tools → Computer control: controls computer
- Agent engine → Browser identities: uses identities (evidence: `invisible_engine_dots/nanobot/dots/engine.py`)
- Browser identities → Websites: browses
- Agent engine → Guest automations: runs automations
- Channel adapters → Telegram: connects
- Channel adapters → WhatsApp: connects
