# maxmasai/maxdots architecture

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

- Interactive diagram: https://gitdiagram.com/maxmasai/maxdots
- Repository: https://github.com/maxmasai/maxdots

## Overview

Maxdots is a self-hosted workspace for personal AI agents (“dots”), combining chat, channels, computer-use automation, integrations, and voice. The main workflow is a user sending a task in chat, server actions dispatching it to the agent runtime, and the dot working with its configured model and computer; persistent workspace data and events support the UI. README capabilities also include multi-agent channels, approvals, app integrations, and persistent voice calls. Source excerpts do not expose every runtime dispatch, so uncertain links are omitted or marked unverified.

Main entry points: [`src/app/actions.ts`](https://github.com/maxmasai/maxdots/blob/main/src/app/actions.ts) (Server actions), [`src/server/repo.ts`](https://github.com/maxmasai/maxdots/blob/main/src/server/repo.ts) (Workspace repository), [`src/server/agent/runtime.ts`](https://github.com/maxmasai/maxdots/blob/main/src/server/agent/runtime.ts) (Agent runtime), [`src/server/vault.ts`](https://github.com/maxmasai/maxdots/blob/main/src/server/vault.ts) (Credential vault)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_chat["Chat workspace<br/>[Chat.tsx]"]
  node_channels["Channels<br/>[ChannelView.tsx]"]
  node_calls["Calls hub<br/>[CallsView.tsx]"]
  node_settings["Settings<br/>[SettingsView.tsx]"]
  node_avatars["Dot avatars<br/>[DotOrb.tsx]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_actions["Server actions<br/>[actions.ts]"]
  node_runtime["Agent runtime<br/>[runtime.ts]"]
  node_models["Model selection<br/>[client.ts]"]
end

subgraph group_capabilities["Dot capabilities"]
  node_computer["Computer modes<br/>[index.ts]"]
  node_browser["Browser automation<br/>[browser.ts]"]
  node_integrations["App integrations<br/>[composio.ts]"]
  node_triggers["App triggers<br/>[triggers.ts]"]
  node_voice["Persistent voice<br/>[voiceCall.ts]"]
end

subgraph group_state["Persistence and events"]
  node_repo["Workspace repository<br/>[repo.ts]"]
  node_database[("SQLite database<br/>[db.ts]")]
  node_vault[("Credential vault<br/>[vault.ts]")]
  node_bus["Event bus<br/>[bus.ts]"]
  node_snapshot["Workspace snapshot<br/>[snapshot.ts]"]
  node_clientstore["Client state<br/>[store.ts]"]
  node_eventsapi["Event stream API<br/>[route.ts]"]
end

node_user(("User"))

node_user -->|"sends task"| node_chat
node_chat -->|"submits messages"| node_actions
node_actions -->|"dispatches task"| node_runtime
node_actions -->|"manages workspace"| node_repo
node_actions -->|"uses computer"| node_computer
node_actions -->|"saves credentials"| node_vault
node_actions -->|"emits updates"| node_bus
node_runtime -.->|"uses tools"| node_computer
node_runtime -.->|"selects model"| node_models
node_models -->|"reads secrets"| node_vault
node_models -->|"reads settings"| node_database
node_computer -->|"delegates browser work"| node_browser
node_repo -->|"reads and writes"| node_database
node_repo -->|"emits changes"| node_bus
node_vault -->|"stores encrypted passwords"| node_repo
node_settings -->|"updates configuration"| node_actions
node_calls -->|"starts calls"| node_voice
node_voice -->|"sends voice tasks"| node_actions
node_channels -.->|"coordinates conversations"| node_actions
node_integrations -->|"seals tokens"| node_vault
node_triggers -.->|"starts agent tasks"| node_runtime
node_eventsapi -->|"subscribes to events"| node_bus
node_eventsapi -->|"loads initial state"| node_snapshot
node_clientstore -.->|"opens event stream"| node_eventsapi
node_snapshot -->|"collects workspace data"| node_repo
node_chat -->|"renders dots"| node_avatars

click node_chat "https://github.com/maxmasai/maxdots/blob/main/src/components/Chat.tsx"
click node_channels "https://github.com/maxmasai/maxdots/blob/main/src/components/ChannelView.tsx"
click node_calls "https://github.com/maxmasai/maxdots/blob/main/src/components/CallsView.tsx"
click node_settings "https://github.com/maxmasai/maxdots/blob/main/src/components/SettingsView.tsx"
click node_avatars "https://github.com/maxmasai/maxdots/blob/main/src/components/DotOrb.tsx"
click node_actions "https://github.com/maxmasai/maxdots/blob/main/src/app/actions.ts"
click node_runtime "https://github.com/maxmasai/maxdots/blob/main/src/server/agent/runtime.ts"
click node_models "https://github.com/maxmasai/maxdots/blob/main/src/server/agent/client.ts"
click node_computer "https://github.com/maxmasai/maxdots/blob/main/src/server/computer/index.ts"
click node_browser "https://github.com/maxmasai/maxdots/blob/main/src/server/computer/browser.ts"
click node_integrations "https://github.com/maxmasai/maxdots/blob/main/src/server/composio.ts"
click node_triggers "https://github.com/maxmasai/maxdots/blob/main/src/server/triggers.ts"
click node_voice "https://github.com/maxmasai/maxdots/blob/main/src/lib/voiceCall.ts"
click node_repo "https://github.com/maxmasai/maxdots/blob/main/src/server/repo.ts"
click node_database "https://github.com/maxmasai/maxdots/blob/main/src/server/db.ts"
click node_vault "https://github.com/maxmasai/maxdots/blob/main/src/server/vault.ts"
click node_bus "https://github.com/maxmasai/maxdots/blob/main/src/server/bus.ts"
click node_snapshot "https://github.com/maxmasai/maxdots/blob/main/src/server/snapshot.ts"
click node_clientstore "https://github.com/maxmasai/maxdots/blob/main/src/lib/store.ts"
click node_eventsapi "https://github.com/maxmasai/maxdots/blob/main/src/app/api/events/route.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,node_channels,node_calls,node_settings,node_avatars,node_user toneBlue
class node_actions,node_runtime,node_models toneAmber
class node_computer,node_browser,node_integrations,node_triggers,node_voice toneMint
class node_repo,node_database,node_vault,node_bus,node_snapshot,node_clientstore,node_eventsapi toneRose
```

## Components

### Workspace UI

- [Chat workspace](https://github.com/maxmasai/maxdots/blob/main/src/components/Chat.tsx): `src/components/Chat.tsx`
- [Channels](https://github.com/maxmasai/maxdots/blob/main/src/components/ChannelView.tsx): `src/components/ChannelView.tsx`
- [Calls hub](https://github.com/maxmasai/maxdots/blob/main/src/components/CallsView.tsx): `src/components/CallsView.tsx`
- [Settings](https://github.com/maxmasai/maxdots/blob/main/src/components/SettingsView.tsx): `src/components/SettingsView.tsx`
- [Dot avatars](https://github.com/maxmasai/maxdots/blob/main/src/components/DotOrb.tsx): `src/components/DotOrb.tsx`

### Agent orchestration

- [Server actions](https://github.com/maxmasai/maxdots/blob/main/src/app/actions.ts): `src/app/actions.ts`
- [Agent runtime](https://github.com/maxmasai/maxdots/blob/main/src/server/agent/runtime.ts): `src/server/agent/runtime.ts`
- [Model selection](https://github.com/maxmasai/maxdots/blob/main/src/server/agent/client.ts): `src/server/agent/client.ts`

### Dot capabilities

- [Computer modes](https://github.com/maxmasai/maxdots/blob/main/src/server/computer/index.ts): `src/server/computer/index.ts`
- [Browser automation](https://github.com/maxmasai/maxdots/blob/main/src/server/computer/browser.ts): `src/server/computer/browser.ts`
- [App integrations](https://github.com/maxmasai/maxdots/blob/main/src/server/composio.ts): `src/server/composio.ts`
- [App triggers](https://github.com/maxmasai/maxdots/blob/main/src/server/triggers.ts): `src/server/triggers.ts`
- [Persistent voice](https://github.com/maxmasai/maxdots/blob/main/src/lib/voiceCall.ts): `src/lib/voiceCall.ts`

### Persistence and events

- [Workspace repository](https://github.com/maxmasai/maxdots/blob/main/src/server/repo.ts): `src/server/repo.ts`
- [SQLite database](https://github.com/maxmasai/maxdots/blob/main/src/server/db.ts): `src/server/db.ts`
- [Credential vault](https://github.com/maxmasai/maxdots/blob/main/src/server/vault.ts): `src/server/vault.ts`
- [Event bus](https://github.com/maxmasai/maxdots/blob/main/src/server/bus.ts): `src/server/bus.ts`
- [Workspace snapshot](https://github.com/maxmasai/maxdots/blob/main/src/server/snapshot.ts): `src/server/snapshot.ts`
- [Client state](https://github.com/maxmasai/maxdots/blob/main/src/lib/store.ts): `src/lib/store.ts`
- [Event stream API](https://github.com/maxmasai/maxdots/blob/main/src/app/api/events/route.ts): `src/app/api/events/route.ts`

### Other components

- **User**

## Connections

- User → Chat workspace: sends task
- Chat workspace → Server actions: submits messages (evidence: `src/components/Chat.tsx`)
- Server actions → Agent runtime: dispatches task (evidence: `src/app/actions.ts`)
- Server actions → Workspace repository: manages workspace (evidence: `src/app/actions.ts`)
- Server actions → Computer modes: uses computer (evidence: `src/app/actions.ts`)
- Server actions → Credential vault: saves credentials (evidence: `src/app/actions.ts`)
- Server actions → Event bus: emits updates (evidence: `src/app/actions.ts`)
- Agent runtime → Computer modes: uses tools
- Agent runtime → Model selection: selects model
- Model selection → Credential vault: reads secrets (evidence: `src/server/agent/client.ts`)
- Model selection → SQLite database: reads settings (evidence: `src/server/agent/client.ts`)
- Computer modes → Browser automation: delegates browser work (evidence: `src/server/computer/index.ts`)
- Workspace repository → SQLite database: reads and writes (evidence: `src/server/repo.ts`)
- Workspace repository → Event bus: emits changes (evidence: `src/server/repo.ts`)
- Credential vault → Workspace repository: stores encrypted passwords (evidence: `src/server/vault.ts`)
- Settings → Server actions: updates configuration (evidence: `src/components/SettingsView.tsx`)
- Calls hub → Persistent voice: starts calls (evidence: `src/components/CallsView.tsx`)
- Persistent voice → Server actions: sends voice tasks (evidence: `src/lib/voiceCall.ts`)
- Channels → Server actions: coordinates conversations
- App integrations → Credential vault: seals tokens (evidence: `src/server/composio.ts`)
- App triggers → Agent runtime: starts agent tasks
- Event stream API → Event bus: subscribes to events (evidence: `src/app/api/events/route.ts`)
- Event stream API → Workspace snapshot: loads initial state (evidence: `src/app/api/events/route.ts`)
- Client state → Event stream API: opens event stream
- Workspace snapshot → Workspace repository: collects workspace data (evidence: `src/server/snapshot.ts`)
- Chat workspace → Dot avatars: renders dots (evidence: `src/components/Chat.tsx`)
