# aegntic/don-bot architecture

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

- Interactive diagram: https://gitdiagram.com/aegntic/don-bot
- Repository: https://github.com/aegntic/don-bot

## Overview

Nod is a local personal AI agent that handles work across connected apps and real websites, using a user-selected model and requesting approval when an action is not covered by the user’s rules. The principal flow is a user request entering the chat/server, becoming a thread turn, and being executed by the agent runtime through app integrations or its computer/browser; results and approval requests return through the conversation. The graph also preserves the README’s memory, scheduled/proactive work, vault, and usage capabilities. Some subsystem paths and relationships come from the SOURCE INDEX or README rather than sampled implementation excerpts.

Main entry points: [`src/runtime/index.ts`](https://github.com/aegntic/don-bot/blob/main/src/runtime/index.ts) (Agent runtime), [`src/server/thread.ts`](https://github.com/aegntic/don-bot/blob/main/src/server/thread.ts) (Threads and turns), [`src/server/app.ts`](https://github.com/aegntic/don-bot/blob/main/src/server/app.ts) (Chat API), [`src/server/object-storage.ts`](https://github.com/aegntic/don-bot/blob/main/src/server/object-storage.ts) (Private object storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Conversation and control"]
  node_chat["Chat API<br/>[app.ts]"]
  node_thread["Threads and turns<br/>[thread.ts]"]
  node_tasks["Tasks and schedules<br/>[tasks.ts]"]
  node_contracts["Shared contracts<br/>[contracts.ts]"]
  node_presentation["Action presentation<br/>[presentation.ts]"]
end

subgraph group_execution["Agent execution"]
  node_agent["Agent runtime<br/>[index.ts]"]
  node_agentport["Agent port<br/>[agent.ts]"]
  node_models{{"Model providers<br/>[models.ts]"}}
  node_proactivity["Proactivity<br/>[proactivity.ts]"]
end

subgraph group_connectors["Apps and computer"]
  node_computerport["Computer port<br/>[computer.ts]"]
  node_browser["Browser providers<br/>[client.ts]"]
  node_integrations["App integrations<br/>[integrations.ts]"]
  node_externalapps{{"Connected services"}}
end

subgraph group_state["Local state and trust"]
  node_database[("Database<br/>[db.ts]")]
  node_transaction["Transactions<br/>[transaction.ts]"]
  node_objectstorage[("Private object storage<br/>[object-storage.ts]")]
  node_objectport["Object storage port<br/>[object-storage.ts]"]
  node_files["File constraints<br/>[files.ts]"]
  node_trust["Trust review<br/>[trust-review.ts]"]
  node_vault["Vault credentials<br/>[tasks.tsx]"]
  node_memory["Personal memory<br/>[memory-recall.ts]"]
  node_analytics["Usage analytics<br/>[analytics.ts]"]
end

subgraph group_experience["User experience"]
  node_web["Web interface<br/>[app.tsx]"]
  node_appconnections["App connections UI<br/>[apps.tsx]"]
  node_accountmanager["Account manager"]
  node_desktop["Desktop runtime<br/>[main.mjs]"]
  node_desktopengine["Local engine<br/>[engine.mjs]"]
end

node_user(("User"))

node_user -->|"submits request"| node_web
node_web -.->|"sends chat"| node_chat
node_chat -->|"manages turns"| node_thread
node_thread -.->|"runs agent"| node_agent
node_tasks -->|"starts turns"| node_thread
node_thread -->|"persists conversation"| node_database
node_thread -->|"uses transactions"| node_transaction
node_agent -.->|"implements agent"| node_agentport
node_agent -->|"uses selected model"| node_models
node_agent -->|"uses computer"| node_computerport
node_computerport -->|"implemented by"| node_browser
node_agent -->|"uses app tools"| node_integrations
node_integrations -->|"acts in services"| node_externalapps
node_user -->|"connects apps"| node_appconnections
node_appconnections -->|"manages accounts"| node_accountmanager
node_appconnections -.->|"configures connections"| node_integrations
node_objectstorage -->|"uses transactions"| node_transaction
node_objectstorage -->|"implements store"| node_objectport
node_objectstorage -->|"validates limits"| node_files
node_agent -->|"checks action rules"| node_trust
node_trust -->|"requests approval"| node_user
node_agent -->|"enters secrets privately"| node_vault
node_agent -->|"recalls facts"| node_memory
node_agent -->|"supports proactive work"| node_proactivity
node_tasks -.->|"schedules checks"| node_proactivity
node_chat -->|"records usage"| node_analytics
node_desktop -->|"starts engine"| node_desktopengine
node_desktopengine -->|"loads server"| node_chat
node_thread -->|"formats results"| node_presentation
node_presentation -->|"renders results"| node_web

click node_web "https://github.com/aegntic/don-bot/blob/main/src/web/app.tsx"
click node_chat "https://github.com/aegntic/don-bot/blob/main/src/server/app.ts"
click node_thread "https://github.com/aegntic/don-bot/blob/main/src/server/thread.ts"
click node_tasks "https://github.com/aegntic/don-bot/blob/main/src/server/tasks.ts"
click node_contracts "https://github.com/aegntic/don-bot/blob/main/src/shared/contracts.ts"
click node_agent "https://github.com/aegntic/don-bot/blob/main/src/runtime/index.ts"
click node_agentport "https://github.com/aegntic/don-bot/blob/main/src/ports/agent.ts"
click node_computerport "https://github.com/aegntic/don-bot/blob/main/src/ports/computer.ts"
click node_browser "https://github.com/aegntic/don-bot/blob/main/src/providers/container-browser/client.ts"
click node_integrations "https://github.com/aegntic/don-bot/blob/main/src/ports/integrations.ts"
click node_appconnections "https://github.com/aegntic/don-bot/blob/main/src/web/pages/apps.tsx"
click node_accountmanager "https://github.com/aegntic/don-bot/blob/main/src/web/components/app-account-manager.tsx"
click node_models "https://github.com/aegntic/don-bot/blob/main/src/shared/models.ts"
click node_database "https://github.com/aegntic/don-bot/blob/main/src/server/db.ts"
click node_transaction "https://github.com/aegntic/don-bot/blob/main/src/server/transaction.ts"
click node_objectstorage "https://github.com/aegntic/don-bot/blob/main/src/server/object-storage.ts"
click node_objectport "https://github.com/aegntic/don-bot/blob/main/src/ports/object-storage.ts"
click node_files "https://github.com/aegntic/don-bot/blob/main/src/shared/files.ts"
click node_trust "https://github.com/aegntic/don-bot/blob/main/src/server/trust-review.ts"
click node_vault "https://github.com/aegntic/don-bot/blob/main/src/web/pages/tasks.tsx"
click node_memory "https://github.com/aegntic/don-bot/blob/main/src/ports/memory-recall.ts"
click node_proactivity "https://github.com/aegntic/don-bot/blob/main/src/ports/proactivity.ts"
click node_analytics "https://github.com/aegntic/don-bot/blob/main/src/server/analytics.ts"
click node_desktop "https://github.com/aegntic/don-bot/blob/main/desktop/main/main.mjs"
click node_desktopengine "https://github.com/aegntic/don-bot/blob/main/desktop/main/engine.mjs"
click node_presentation "https://github.com/aegntic/don-bot/blob/main/src/shared/presentation.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_thread,node_tasks,node_contracts,node_presentation,node_user toneBlue
class node_agent,node_agentport,node_models,node_proactivity toneAmber
class node_computerport,node_browser,node_integrations,node_externalapps toneMint
class node_database,node_transaction,node_objectstorage,node_objectport,node_files,node_trust,node_vault,node_memory,node_analytics toneRose
class node_web,node_appconnections,node_accountmanager,node_desktop,node_desktopengine toneIndigo
```

## Components

### Conversation and control

- [Chat API](https://github.com/aegntic/don-bot/blob/main/src/server/app.ts): `src/server/app.ts`
- [Threads and turns](https://github.com/aegntic/don-bot/blob/main/src/server/thread.ts): `src/server/thread.ts`
- [Tasks and schedules](https://github.com/aegntic/don-bot/blob/main/src/server/tasks.ts): `src/server/tasks.ts`
- [Shared contracts](https://github.com/aegntic/don-bot/blob/main/src/shared/contracts.ts): `src/shared/contracts.ts`
- [Action presentation](https://github.com/aegntic/don-bot/blob/main/src/shared/presentation.ts): `src/shared/presentation.ts`

### Agent execution

- [Agent runtime](https://github.com/aegntic/don-bot/blob/main/src/runtime/index.ts): `src/runtime/index.ts`
- [Agent port](https://github.com/aegntic/don-bot/blob/main/src/ports/agent.ts): `src/ports/agent.ts`
- [Model providers](https://github.com/aegntic/don-bot/blob/main/src/shared/models.ts): `src/shared/models.ts`
- [Proactivity](https://github.com/aegntic/don-bot/blob/main/src/ports/proactivity.ts): `src/ports/proactivity.ts`

### Apps and computer

- [Computer port](https://github.com/aegntic/don-bot/blob/main/src/ports/computer.ts): `src/ports/computer.ts`
- [Browser providers](https://github.com/aegntic/don-bot/blob/main/src/providers/container-browser/client.ts): `src/providers/container-browser/client.ts`
- [App integrations](https://github.com/aegntic/don-bot/blob/main/src/ports/integrations.ts): `src/ports/integrations.ts`
- **Connected services**

### Local state and trust

- [Database](https://github.com/aegntic/don-bot/blob/main/src/server/db.ts): `src/server/db.ts`
- [Transactions](https://github.com/aegntic/don-bot/blob/main/src/server/transaction.ts): `src/server/transaction.ts`
- [Private object storage](https://github.com/aegntic/don-bot/blob/main/src/server/object-storage.ts): `src/server/object-storage.ts`
- [Object storage port](https://github.com/aegntic/don-bot/blob/main/src/ports/object-storage.ts): `src/ports/object-storage.ts`
- [File constraints](https://github.com/aegntic/don-bot/blob/main/src/shared/files.ts): `src/shared/files.ts`
- [Trust review](https://github.com/aegntic/don-bot/blob/main/src/server/trust-review.ts): `src/server/trust-review.ts`
- [Vault credentials](https://github.com/aegntic/don-bot/blob/main/src/web/pages/tasks.tsx): `src/web/pages/tasks.tsx`
- [Personal memory](https://github.com/aegntic/don-bot/blob/main/src/ports/memory-recall.ts): `src/ports/memory-recall.ts`
- [Usage analytics](https://github.com/aegntic/don-bot/blob/main/src/server/analytics.ts): `src/server/analytics.ts`

### User experience

- [Web interface](https://github.com/aegntic/don-bot/blob/main/src/web/app.tsx): `src/web/app.tsx`
- [App connections UI](https://github.com/aegntic/don-bot/blob/main/src/web/pages/apps.tsx): `src/web/pages/apps.tsx`
- [Account manager](https://github.com/aegntic/don-bot/blob/main/src/web/components/app-account-manager.tsx): `src/web/components/app-account-manager.tsx`
- [Desktop runtime](https://github.com/aegntic/don-bot/blob/main/desktop/main/main.mjs): `desktop/main/main.mjs`
- [Local engine](https://github.com/aegntic/don-bot/blob/main/desktop/main/engine.mjs): `desktop/main/engine.mjs`

### Other components

- **User**

## Connections

- User → Web interface: submits request (evidence: `README.md`)
- Web interface → Chat API: sends chat
- Chat API → Threads and turns: manages turns (evidence: `src/server/app.ts`)
- Threads and turns → Agent runtime: runs agent
- Tasks and schedules → Threads and turns: starts turns (evidence: `src/server/tasks.ts`)
- Threads and turns → Database: persists conversation (evidence: `src/server/thread.ts`)
- Threads and turns → Transactions: uses transactions (evidence: `src/server/thread.ts`)
- Agent runtime → Agent port: implements agent (evidence: `src/runtime/index.ts`)
- Agent runtime → Model providers: uses selected model (evidence: `README.md`)
- Agent runtime → Computer port: uses computer (evidence: `src/runtime/index.ts`)
- Computer port → Browser providers: implemented by (evidence: `src/providers/container-browser/client.ts`)
- Agent runtime → App integrations: uses app tools (evidence: `README.md`)
- App integrations → Connected services: acts in services (evidence: `README.md`)
- User → App connections UI: connects apps (evidence: `README.md`)
- App connections UI → Account manager: manages accounts (evidence: `src/web/pages/apps.tsx`)
- App connections UI → App integrations: configures connections
- Private object storage → Transactions: uses transactions (evidence: `src/server/object-storage.ts`)
- Private object storage → Object storage port: implements store (evidence: `src/server/object-storage.ts`)
- Private object storage → File constraints: validates limits (evidence: `src/server/object-storage.ts`)
- Agent runtime → Trust review: checks action rules (evidence: `README.md`)
- Trust review → User: requests approval (evidence: `README.md`)
- Agent runtime → Vault credentials: enters secrets privately (evidence: `README.md`)
- Agent runtime → Personal memory: recalls facts (evidence: `README.md`)
- Agent runtime → Proactivity: supports proactive work (evidence: `README.md`)
- Tasks and schedules → Proactivity: schedules checks
- Chat API → Usage analytics: records usage (evidence: `src/server/analytics.ts`)
- Desktop runtime → Local engine: starts engine (evidence: `desktop/main/engine.mjs`)
- Local engine → Chat API: loads server (evidence: `desktop/main/engine.mjs`)
- Threads and turns → Action presentation: formats results (evidence: `src/server/thread.ts`)
- Action presentation → Web interface: renders results (evidence: `README.md`)
