# darkspacey/nan-itself architecture

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

- Interactive diagram: https://gitdiagram.com/darkspacey/nan-itself
- Repository: https://github.com/darkspacey/nan-itself

## Overview

NAN-itself is a local-first autonomous agent framework with a web interface. A user sends a message through the UI and local HTTP/WebSocket gateway; the application routes input to the inbox module, and the agent runs turn-based LLM reasoning, using tools, skills, and ambient module context before streaming events back to the UI. The framework also supports hot-reloaded builtin/workspace providers and reactive module channels. Main runtime links follow the README and sampled app, engine, module, and frontend code; unsampled internals are represented only where documented.

Main entry points: [`backend/nan_itself/modules/runtime.py`](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/modules/runtime.py) (Module facade), [`backend/nan_itself/agent/core.py`](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/agent/core.py) (Agent loop), [`backend/nan_itself/app.py`](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/app.py) (App composition), [`backend/nan_itself/gateway.py`](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/gateway.py) (HTTP gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application runtime"]
  node_app["App composition<br/>[app.py]"]
  node_gateway["HTTP gateway<br/>[gateway.py]"]
  node_events["Event bus<br/>[events.py]"]
end

subgraph group_reason["Agent reasoning"]
  node_agent["Agent loop<br/>[core.py]"]
  node_engine["Step engine<br/>[engine.py]"]
  node_prompts["Prompt assembly<br/>[prompts.py]"]
  node_llm["LLM provider<br/>[llm.py]"]
  node_verbs["Agent verbs<br/>[verbs.py]"]
end

subgraph group_extensions["Agent extensions"]
  node_tool_runtime["Tool runtime<br/>[runtime.py]"]
  node_tool_sources["Builtin and workspace tools<br/>[search.py]"]
  node_skills["Skill runtime<br/>[runtime.py]"]
  node_modules["Module facade<br/>[runtime.py]"]
  node_ambient["Ambient modules<br/>[vision.py]"]
  node_inbox["Inbox module<br/>[inbox.py]"]
  node_workspace_module["Workspace module<br/>[workspace.py]"]
  node_module_store[("Module state<br/>[persistence.py]")]
end

subgraph group_interface["User interface"]
  node_web_app["Web UI<br/>[App.tsx]"]
  node_stream_hook["WebSocket stream<br/>[useAgentStream2.ts]"]
  node_composer["Message composer<br/>[Composer.tsx]"]
end

node_user(("User"))
node_llm_service{{"LLM service"}}
node_mcp_servers{{"MCP servers"}}

node_user -->|"enters message"| node_composer
node_composer -->|"sends input"| node_stream_hook
node_stream_hook -->|"WebSocket input"| node_gateway
node_gateway -->|"dispatches input"| node_app
node_app -->|"queues text"| node_inbox
node_app -->|"starts gateway"| node_gateway
node_app -->|"starts loop"| node_agent
node_app -->|"starts providers"| node_tool_runtime
node_app -->|"starts modules"| node_modules
node_agent -->|"runs turn"| node_engine
node_engine -->|"builds messages"| node_prompts
node_engine -->|"requests completion"| node_llm
node_llm -->|"calls model"| node_llm_service
node_engine -->|"dispatches calls"| node_verbs
node_verbs -->|"invokes tool"| node_tool_runtime
node_tool_runtime -->|"loads providers"| node_tool_sources
node_tool_runtime -.->|"calls MCP tools"| node_mcp_servers
node_agent -->|"uses skills"| node_skills
node_agent -->|"gets turn context"| node_modules
node_modules -->|"runs perception"| node_ambient
node_modules -->|"manages module"| node_inbox
node_modules -->|"loads module"| node_workspace_module
node_modules -->|"persists state"| node_module_store
node_agent -.->|"invokes channels"| node_modules
node_modules -->|"returns context"| node_agent
node_gateway -->|"publishes events"| node_events
node_agent -->|"emits turn events"| node_events
node_events -->|"streams events"| node_gateway
node_gateway -->|"sends events"| node_stream_hook
node_stream_hook -->|"updates snapshot"| node_web_app
node_web_app -->|"shows response"| node_user

click node_app "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/app.py"
click node_gateway "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/gateway.py"
click node_events "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/events.py"
click node_agent "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/agent/core.py"
click node_engine "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/agent/engine.py"
click node_prompts "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/agent/prompts.py"
click node_llm "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/utils/llm.py"
click node_verbs "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/agent/verbs.py"
click node_tool_runtime "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/tools/runtime.py"
click node_tool_sources "https://github.com/darkspacey/nan-itself/blob/main/builtin/tools/local/search.py"
click node_skills "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/skills/runtime.py"
click node_modules "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/modules/runtime.py"
click node_ambient "https://github.com/darkspacey/nan-itself/blob/main/builtin/modules/vision.py"
click node_inbox "https://github.com/darkspacey/nan-itself/blob/main/builtin/modules/inbox.py"
click node_workspace_module "https://github.com/darkspacey/nan-itself/blob/main/workspace/modules/workspace.py"
click node_module_store "https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/modules/persistence.py"
click node_web_app "https://github.com/darkspacey/nan-itself/blob/main/frontend/app/src/App.tsx"
click node_stream_hook "https://github.com/darkspacey/nan-itself/blob/main/frontend/app/src/state/useAgentStream2.ts"
click node_composer "https://github.com/darkspacey/nan-itself/blob/main/frontend/app/src/shell/Composer.tsx"

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_app,node_gateway,node_events,node_user toneBlue
class node_agent,node_engine,node_prompts,node_llm,node_verbs toneAmber
class node_tool_runtime,node_tool_sources,node_skills,node_modules,node_ambient,node_inbox,node_workspace_module,node_module_store,node_mcp_servers toneMint
class node_web_app,node_stream_hook,node_composer toneRose
class node_llm_service toneIndigo
```

## Components

### Application runtime

- [App composition](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/app.py): `backend/nan_itself/app.py`
- [HTTP gateway](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/gateway.py): `backend/nan_itself/gateway.py`
- [Event bus](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/events.py): `backend/nan_itself/events.py`

### Agent reasoning

- [Agent loop](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/agent/core.py): `backend/nan_itself/agent/core.py`
- [Step engine](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/agent/engine.py): `backend/nan_itself/agent/engine.py`
- [Prompt assembly](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/agent/prompts.py): `backend/nan_itself/agent/prompts.py`
- [LLM provider](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/utils/llm.py): `backend/nan_itself/utils/llm.py`
- [Agent verbs](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/agent/verbs.py): `backend/nan_itself/agent/verbs.py`

### Agent extensions

- [Tool runtime](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/tools/runtime.py): `backend/nan_itself/tools/runtime.py`
- [Builtin and workspace tools](https://github.com/darkspacey/nan-itself/blob/main/builtin/tools/local/search.py): `builtin/tools/local/search.py`
- [Skill runtime](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/skills/runtime.py): `backend/nan_itself/skills/runtime.py`
- [Module facade](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/modules/runtime.py): `backend/nan_itself/modules/runtime.py`
- [Ambient modules](https://github.com/darkspacey/nan-itself/blob/main/builtin/modules/vision.py): `builtin/modules/vision.py`
- [Inbox module](https://github.com/darkspacey/nan-itself/blob/main/builtin/modules/inbox.py): `builtin/modules/inbox.py`
- [Workspace module](https://github.com/darkspacey/nan-itself/blob/main/workspace/modules/workspace.py): `workspace/modules/workspace.py`
- [Module state](https://github.com/darkspacey/nan-itself/blob/main/backend/nan_itself/modules/persistence.py): `backend/nan_itself/modules/persistence.py`

### User interface

- [Web UI](https://github.com/darkspacey/nan-itself/blob/main/frontend/app/src/App.tsx): `frontend/app/src/App.tsx`
- [WebSocket stream](https://github.com/darkspacey/nan-itself/blob/main/frontend/app/src/state/useAgentStream2.ts): `frontend/app/src/state/useAgentStream2.ts`
- [Message composer](https://github.com/darkspacey/nan-itself/blob/main/frontend/app/src/shell/Composer.tsx): `frontend/app/src/shell/Composer.tsx`

### Other components

- **User**
- **LLM service**
- **MCP servers**

## Connections

- User → Message composer: enters message
- Message composer → WebSocket stream: sends input
- WebSocket stream → HTTP gateway: WebSocket input
- HTTP gateway → App composition: dispatches input
- App composition → Inbox module: queues text
- App composition → HTTP gateway: starts gateway
- App composition → Agent loop: starts loop
- App composition → Tool runtime: starts providers
- App composition → Module facade: starts modules
- Agent loop → Step engine: runs turn
- Step engine → Prompt assembly: builds messages
- Step engine → LLM provider: requests completion
- LLM provider → LLM service: calls model
- Step engine → Agent verbs: dispatches calls
- Agent verbs → Tool runtime: invokes tool
- Tool runtime → Builtin and workspace tools: loads providers
- Tool runtime → MCP servers: calls MCP tools
- Agent loop → Skill runtime: uses skills
- Agent loop → Module facade: gets turn context
- Module facade → Ambient modules: runs perception
- Module facade → Inbox module: manages module
- Module facade → Workspace module: loads module
- Module facade → Module state: persists state
- Agent loop → Module facade: invokes channels
- Module facade → Agent loop: returns context
- HTTP gateway → Event bus: publishes events
- Agent loop → Event bus: emits turn events
- Event bus → HTTP gateway: streams events
- HTTP gateway → WebSocket stream: sends events
- WebSocket stream → Web UI: updates snapshot
- Web UI → User: shows response