# n8n-io/nod architecture

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

- Interactive diagram: https://gitdiagram.com/n8n-io/nod
- Repository: https://github.com/n8n-io/nod

## Overview

Nod is a personal AI agent that runs locally or on a server, connects to work apps and websites, and can ask for approval before acting. The main workflow is a user request entering through chat, being managed as a thread and turn, then handled by the agent runtime using models, integrations, and a computer/browser; results and approval requests return through the server to the user interface. Memory, scheduled/proactive work, trust controls, and usage visibility are important product branches. Some subsystem links are documented by the README but their implementation was not sampled.

Main entry points: [`src/runtime/index.ts`](https://github.com/n8n-io/nod/blob/main/src/runtime/index.ts) (Agent runtime), [`src/server/app.ts`](https://github.com/n8n-io/nod/blob/main/src/server/app.ts) (Server API), [`src/server/thread.ts`](https://github.com/n8n-io/nod/blob/main/src/server/thread.ts) (Threads and turns), [`src/server/tasks.ts`](https://github.com/n8n-io/nod/blob/main/src/server/tasks.ts) (Tasks and schedules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Chat and workspace UI<br/>[app.tsx]"]
  node_app_connections["App connections<br/>[apps.tsx]"]
  node_desktop["Desktop host<br/>[main.mjs]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_server_app["Server API<br/>[app.ts]"]
  node_thread["Threads and turns<br/>[thread.ts]"]
  node_tasks["Tasks and schedules<br/>[tasks.ts]"]
  node_runtime["Agent runtime<br/>[index.ts]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_agent_port["Agent port<br/>[agent.ts]"]
  node_computer_port["Computer port<br/>[computer.ts]"]
  node_browser["Browser automation<br/>[client.ts]"]
  node_integrations["App integrations<br/>[integrations.ts]"]
  node_model_provider["Model providers<br/>[models.ts]"]
end

subgraph group_trust["Trust and memory"]
  node_trust_review["Trust review<br/>[trust-review.ts]"]
  node_memory["Memory and skills<br/>[memory-curator.ts]"]
  node_vault["Private credentials<br/>[contracts.ts]"]
end

subgraph group_platform["Platform services"]
  node_database[("Application database<br/>[db.ts]")]
  node_object_storage[("Private object storage<br/>[object-storage.ts]")]
  node_usage["Usage and analytics<br/>[analytics.ts]"]
end

node_user(("User"))
node_external_apps{{"Connected apps and web"}}

node_user -.->|"requests work"| node_web
node_web -.->|"sends requests"| node_server_app
node_app_connections -->|"configures connections"| node_server_app
node_desktop -->|"hosts engine"| node_server_app
node_server_app -->|"routes chat"| node_thread
node_server_app -->|"routes tasks"| node_tasks
node_thread -->|"runs turns"| node_runtime
node_tasks -->|"manages task turns"| node_thread
node_runtime -->|"invokes agent"| node_agent_port
node_runtime -->|"uses computer"| node_computer_port
node_browser -->|"implements browser"| node_computer_port
node_runtime -.->|"uses app tools"| node_integrations
node_runtime -.->|"requests inference"| node_model_provider
node_thread -->|"persists thread state"| node_database
node_tasks -->|"persists tasks"| node_database
node_server_app -.->|"checks actions"| node_trust_review
node_runtime -.->|"uses memory"| node_memory
node_runtime -.->|"uses private credentials"| node_vault
node_server_app -->|"serves private files"| node_object_storage
node_object_storage -->|"stores private objects"| node_database
node_runtime -.->|"records usage"| node_usage
node_integrations -.->|"connects to"| node_external_apps
node_browser -.->|"operates websites"| node_external_apps
node_thread -.->|"returns results"| node_web
node_trust_review -.->|"requests approval"| node_user

click node_web "https://github.com/n8n-io/nod/blob/main/src/web/app.tsx"
click node_app_connections "https://github.com/n8n-io/nod/blob/main/src/web/pages/apps.tsx"
click node_desktop "https://github.com/n8n-io/nod/blob/main/desktop/main/main.mjs"
click node_server_app "https://github.com/n8n-io/nod/blob/main/src/server/app.ts"
click node_thread "https://github.com/n8n-io/nod/blob/main/src/server/thread.ts"
click node_tasks "https://github.com/n8n-io/nod/blob/main/src/server/tasks.ts"
click node_runtime "https://github.com/n8n-io/nod/blob/main/src/runtime/index.ts"
click node_agent_port "https://github.com/n8n-io/nod/blob/main/src/ports/agent.ts"
click node_computer_port "https://github.com/n8n-io/nod/blob/main/src/ports/computer.ts"
click node_browser "https://github.com/n8n-io/nod/blob/main/src/providers/container-browser/client.ts"
click node_integrations "https://github.com/n8n-io/nod/blob/main/src/ports/integrations.ts"
click node_model_provider "https://github.com/n8n-io/nod/blob/main/src/providers/pi/models.ts"
click node_trust_review "https://github.com/n8n-io/nod/blob/main/src/server/trust-review.ts"
click node_memory "https://github.com/n8n-io/nod/blob/main/src/providers/pi/memory-curator.ts"
click node_vault "https://github.com/n8n-io/nod/blob/main/src/shared/contracts.ts"
click node_database "https://github.com/n8n-io/nod/blob/main/src/server/db.ts"
click node_object_storage "https://github.com/n8n-io/nod/blob/main/src/server/object-storage.ts"
click node_usage "https://github.com/n8n-io/nod/blob/main/src/server/analytics.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_web,node_app_connections,node_desktop,node_user toneBlue
class node_server_app,node_thread,node_tasks,node_runtime toneAmber
class node_agent_port,node_computer_port,node_browser,node_integrations,node_model_provider toneMint
class node_trust_review,node_memory,node_vault toneRose
class node_database,node_object_storage,node_usage,node_external_apps toneIndigo
```

## Components

### User experience

- [Chat and workspace UI](https://github.com/n8n-io/nod/blob/main/src/web/app.tsx): `src/web/app.tsx`
- [App connections](https://github.com/n8n-io/nod/blob/main/src/web/pages/apps.tsx): `src/web/pages/apps.tsx`
- [Desktop host](https://github.com/n8n-io/nod/blob/main/desktop/main/main.mjs): `desktop/main/main.mjs`

### Agent orchestration

- [Server API](https://github.com/n8n-io/nod/blob/main/src/server/app.ts): `src/server/app.ts`
- [Threads and turns](https://github.com/n8n-io/nod/blob/main/src/server/thread.ts): `src/server/thread.ts`
- [Tasks and schedules](https://github.com/n8n-io/nod/blob/main/src/server/tasks.ts): `src/server/tasks.ts`
- [Agent runtime](https://github.com/n8n-io/nod/blob/main/src/runtime/index.ts): `src/runtime/index.ts`

### Agent capabilities

- [Agent port](https://github.com/n8n-io/nod/blob/main/src/ports/agent.ts): `src/ports/agent.ts`
- [Computer port](https://github.com/n8n-io/nod/blob/main/src/ports/computer.ts): `src/ports/computer.ts`
- [Browser automation](https://github.com/n8n-io/nod/blob/main/src/providers/container-browser/client.ts): `src/providers/container-browser/client.ts`
- [App integrations](https://github.com/n8n-io/nod/blob/main/src/ports/integrations.ts): `src/ports/integrations.ts`
- [Model providers](https://github.com/n8n-io/nod/blob/main/src/providers/pi/models.ts): `src/providers/pi/models.ts`

### Trust and memory

- [Trust review](https://github.com/n8n-io/nod/blob/main/src/server/trust-review.ts): `src/server/trust-review.ts`
- [Memory and skills](https://github.com/n8n-io/nod/blob/main/src/providers/pi/memory-curator.ts): `src/providers/pi/memory-curator.ts`
- [Private credentials](https://github.com/n8n-io/nod/blob/main/src/shared/contracts.ts): `src/shared/contracts.ts`

### Platform services

- [Application database](https://github.com/n8n-io/nod/blob/main/src/server/db.ts): `src/server/db.ts`
- [Private object storage](https://github.com/n8n-io/nod/blob/main/src/server/object-storage.ts): `src/server/object-storage.ts`
- [Usage and analytics](https://github.com/n8n-io/nod/blob/main/src/server/analytics.ts): `src/server/analytics.ts`

### Other components

- **User**
- **Connected apps and web**

## Connections

- User → Chat and workspace UI: requests work (evidence: `README.md`)
- Chat and workspace UI → Server API: sends requests
- App connections → Server API: configures connections (evidence: `src/web/pages/apps.tsx`)
- Desktop host → Server API: hosts engine
- Server API → Threads and turns: routes chat (evidence: `src/server/app.ts`)
- Server API → Tasks and schedules: routes tasks (evidence: `src/server/app.ts`)
- Threads and turns → Agent runtime: runs turns (evidence: `src/server/thread.ts`)
- Tasks and schedules → Threads and turns: manages task turns (evidence: `src/server/tasks.ts`)
- Agent runtime → Agent port: invokes agent (evidence: `src/runtime/index.ts`)
- Agent runtime → Computer port: uses computer (evidence: `src/runtime/index.ts`)
- Browser automation → Computer port: implements browser (evidence: `src/providers/container-browser/client.ts`)
- Agent runtime → App integrations: uses app tools
- Agent runtime → Model providers: requests inference
- Threads and turns → Application database: persists thread state (evidence: `src/server/thread.ts`)
- Tasks and schedules → Application database: persists tasks (evidence: `src/server/tasks.ts`)
- Server API → Trust review: checks actions
- Agent runtime → Memory and skills: uses memory
- Agent runtime → Private credentials: uses private credentials (evidence: `README.md`)
- Server API → Private object storage: serves private files (evidence: `src/server/app.ts`)
- Private object storage → Application database: stores private objects (evidence: `src/server/object-storage.ts`)
- Agent runtime → Usage and analytics: records usage
- App integrations → Connected apps and web: connects to (evidence: `README.md`)
- Browser automation → Connected apps and web: operates websites (evidence: `README.md`)
- Threads and turns → Chat and workspace UI: returns results
- Trust review → User: requests approval (evidence: `README.md`)