# zeraix/zeraix architecture

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

- Interactive diagram: https://gitdiagram.com/zeraix/zeraix
- Repository: https://github.com/zeraix/zeraix

## Overview

Zeraix is a local-first AI desktop workspace. The main workflow is a user sending a task in chat, the agent preparing model context and running turns, and tools acting on files or other resources under configurable approval and sandbox policies. Local model management and inference are central, with cloud providers optional. Separate product branches support recurring workflows, MCP and plugins, document skills, generated and uploaded media, and customizable skins. README capabilities guide this map; unsampled implementation details are represented only where the tree supports a path, and uncertain wiring is omitted.

Main entry points: [`src/lib/agent/runtimeTurn.ts`](https://github.com/zeraix/zeraix/blob/main/src/lib/agent/runtimeTurn.ts) (Turn runtime), [`src/app/agent/chat/page.tsx`](https://github.com/zeraix/zeraix/blob/main/src/app/agent/chat/page.tsx) (Chat workspace), [`src/lib/agent/agentLoop.ts`](https://github.com/zeraix/zeraix/blob/main/src/lib/agent/agentLoop.ts) (Agent loop), [`runtime/crates/agent-runtime/src/server.rs`](https://github.com/zeraix/zeraix/blob/main/runtime/crates/agent-runtime/src/server.rs) (Rust Agent Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_chat["Chat workspace<br/>[page.tsx]"]
  node_chat_turn["Turn coordination<br/>[turnRound.ts]"]
  node_media["Media library<br/>[mediaLibrary.ts]"]
  node_generation["Generation services<br/>[index.ts]"]
  node_skins["Skin packages<br/>[engine.mjs]"]
end

subgraph group_agent["Agent execution"]
  node_context["Context builder<br/>[contextManager.ts]"]
  node_agent_loop["Agent loop<br/>[agentLoop.ts]"]
  node_turn["Turn runtime<br/>[runtimeTurn.ts]"]
  node_rust_bridge["Runtime boundary<br/>[runtimeBoundary.ts]"]
  node_runtime["Rust Agent Runtime<br/>[server.rs]"]
  node_permissions["Tool permissions<br/>[lib.rs]"]
  node_conversation_store[("Conversation storage")]
end

subgraph group_models["Models and inference"]
  node_model_ui["Model library<br/>[page.tsx]"]
  node_model_registry["Model registry<br/>[modelRegistry.ts]"]
  node_local_models["Local model manager<br/>[localModels.mjs]"]
  node_local_server["Local inference server<br/>[localServer.mjs]"]
  node_cloud_models["Cloud model access<br/>[llm.ts]"]
end

subgraph group_extensions["Tools and extensions"]
  node_tools["File tools<br/>[lib.rs]"]
  node_sandbox["Sandbox execution<br/>[engine.mjs]"]
  node_mcp["MCP connections<br/>[client.mjs]"]
  node_plugins[("Plugin system<br/>[store.mjs]")]
  node_skills["Document skills<br/>[runtime.ts]"]
end

subgraph group_automation["Workflow automation"]
  node_automation_ui["Workflow editor<br/>[WorkflowEditor.tsx]"]
  node_automation_dispatch["Run management"]
  node_automation_store[("Workflow data<br/>[db.mjs]")]
end

node_user(("User"))

node_user -->|"sends task"| node_chat
node_chat -->|"starts turn"| node_chat_turn
node_chat_turn -->|"prepares context"| node_context
node_chat_turn -->|"coordinates turn"| node_agent_loop
node_agent_loop -->|"runs turn"| node_turn
node_turn -->|"builds model input"| node_context
node_turn -.->|"requests model"| node_cloud_models
node_model_ui -->|"selects model"| node_model_registry
node_model_registry -->|"manages local models"| node_local_models
node_local_models -->|"starts inference"| node_local_server
node_turn -->|"dispatches tool calls"| node_rust_bridge
node_rust_bridge -->|"sends runtime requests"| node_runtime
node_runtime -->|"checks capabilities"| node_permissions
node_runtime -->|"dispatches tools"| node_tools
node_tools -->|"runs commands"| node_sandbox
node_runtime -.->|"uses MCP tools"| node_mcp
node_turn -->|"persists conversation"| node_conversation_store
node_automation_ui -->|"configures and runs"| node_automation_dispatch
node_automation_dispatch -->|"records run state"| node_automation_store
node_agent_loop -.->|"uses skills"| node_skills
node_agent_loop -.->|"uses extensions"| node_plugins
node_chat -->|"organizes assets"| node_media
node_chat -.->|"requests generation"| node_generation
node_user -->|"chooses models"| node_model_ui
node_user -->|"creates workflows"| node_automation_ui
node_user -->|"customizes appearance"| node_skins

click node_chat "https://github.com/zeraix/zeraix/blob/main/src/app/agent/chat/page.tsx"
click node_chat_turn "https://github.com/zeraix/zeraix/blob/main/src/app/agent/chat/turnRound.ts"
click node_context "https://github.com/zeraix/zeraix/blob/main/src/lib/agent/contextManager.ts"
click node_agent_loop "https://github.com/zeraix/zeraix/blob/main/src/lib/agent/agentLoop.ts"
click node_turn "https://github.com/zeraix/zeraix/blob/main/src/lib/agent/runtimeTurn.ts"
click node_rust_bridge "https://github.com/zeraix/zeraix/blob/main/src/lib/agent/runtimeBoundary.ts"
click node_runtime "https://github.com/zeraix/zeraix/blob/main/runtime/crates/agent-runtime/src/server.rs"
click node_permissions "https://github.com/zeraix/zeraix/blob/main/runtime/crates/agent-permission/src/lib.rs"
click node_tools "https://github.com/zeraix/zeraix/blob/main/runtime/crates/agent-tools/src/lib.rs"
click node_sandbox "https://github.com/zeraix/zeraix/blob/main/electron/tools/sandbox/engine.mjs"
click node_conversation_store "https://github.com/zeraix/zeraix/blob/main/electron/store/conversationStore.mjs"
click node_model_ui "https://github.com/zeraix/zeraix/blob/main/src/app/agent/models/page.tsx"
click node_model_registry "https://github.com/zeraix/zeraix/blob/main/src/lib/ai/modelRegistry.ts"
click node_local_models "https://github.com/zeraix/zeraix/blob/main/electron/llm/localModels.mjs"
click node_local_server "https://github.com/zeraix/zeraix/blob/main/electron/llm/localServer.mjs"
click node_cloud_models "https://github.com/zeraix/zeraix/blob/main/src/lib/ai/llm.ts"
click node_mcp "https://github.com/zeraix/zeraix/blob/main/electron/mcp/client.mjs"
click node_plugins "https://github.com/zeraix/zeraix/blob/main/electron/plugins/store.mjs"
click node_skills "https://github.com/zeraix/zeraix/blob/main/src/lib/ai/skills/runtime.ts"
click node_media "https://github.com/zeraix/zeraix/blob/main/src/lib/ai/mediaLibrary.ts"
click node_generation "https://github.com/zeraix/zeraix/blob/main/src/lib/ai/generation/index.ts"
click node_automation_ui "https://github.com/zeraix/zeraix/blob/main/src/app/agent/automation/WorkflowEditor.tsx"
click node_automation_dispatch "https://github.com/zeraix/zeraix/blob/main/electron/automation/executionManager.mjs"
click node_automation_store "https://github.com/zeraix/zeraix/blob/main/electron/automation/db.mjs"
click node_skins "https://github.com/zeraix/zeraix/blob/main/electron/skins/engine.mjs"

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_chat_turn,node_media,node_generation,node_skins,node_user toneBlue
class node_context,node_agent_loop,node_turn,node_rust_bridge,node_runtime,node_permissions,node_conversation_store toneAmber
class node_model_ui,node_model_registry,node_local_models,node_local_server,node_cloud_models toneMint
class node_tools,node_sandbox,node_mcp,node_plugins,node_skills toneRose
class node_automation_ui,node_automation_dispatch,node_automation_store toneIndigo
```

## Components

### Workspace UI

- [Chat workspace](https://github.com/zeraix/zeraix/blob/main/src/app/agent/chat/page.tsx): `src/app/agent/chat/page.tsx`
- [Turn coordination](https://github.com/zeraix/zeraix/blob/main/src/app/agent/chat/turnRound.ts): `src/app/agent/chat/turnRound.ts`
- [Media library](https://github.com/zeraix/zeraix/blob/main/src/lib/ai/mediaLibrary.ts): `src/lib/ai/mediaLibrary.ts`
- [Generation services](https://github.com/zeraix/zeraix/blob/main/src/lib/ai/generation/index.ts): `src/lib/ai/generation/index.ts`
- [Skin packages](https://github.com/zeraix/zeraix/blob/main/electron/skins/engine.mjs): `electron/skins/engine.mjs`

### Agent execution

- [Context builder](https://github.com/zeraix/zeraix/blob/main/src/lib/agent/contextManager.ts): `src/lib/agent/contextManager.ts`
- [Agent loop](https://github.com/zeraix/zeraix/blob/main/src/lib/agent/agentLoop.ts): `src/lib/agent/agentLoop.ts`
- [Turn runtime](https://github.com/zeraix/zeraix/blob/main/src/lib/agent/runtimeTurn.ts): `src/lib/agent/runtimeTurn.ts`
- [Runtime boundary](https://github.com/zeraix/zeraix/blob/main/src/lib/agent/runtimeBoundary.ts): `src/lib/agent/runtimeBoundary.ts`
- [Rust Agent Runtime](https://github.com/zeraix/zeraix/blob/main/runtime/crates/agent-runtime/src/server.rs): `runtime/crates/agent-runtime/src/server.rs`
- [Tool permissions](https://github.com/zeraix/zeraix/blob/main/runtime/crates/agent-permission/src/lib.rs): `runtime/crates/agent-permission/src/lib.rs`
- [Conversation storage](https://github.com/zeraix/zeraix/blob/main/electron/store/conversationStore.mjs): `electron/store/conversationStore.mjs`

### Models and inference

- [Model library](https://github.com/zeraix/zeraix/blob/main/src/app/agent/models/page.tsx): `src/app/agent/models/page.tsx`
- [Model registry](https://github.com/zeraix/zeraix/blob/main/src/lib/ai/modelRegistry.ts): `src/lib/ai/modelRegistry.ts`
- [Local model manager](https://github.com/zeraix/zeraix/blob/main/electron/llm/localModels.mjs): `electron/llm/localModels.mjs`
- [Local inference server](https://github.com/zeraix/zeraix/blob/main/electron/llm/localServer.mjs): `electron/llm/localServer.mjs`
- [Cloud model access](https://github.com/zeraix/zeraix/blob/main/src/lib/ai/llm.ts): `src/lib/ai/llm.ts`

### Tools and extensions

- [File tools](https://github.com/zeraix/zeraix/blob/main/runtime/crates/agent-tools/src/lib.rs): `runtime/crates/agent-tools/src/lib.rs`
- [Sandbox execution](https://github.com/zeraix/zeraix/blob/main/electron/tools/sandbox/engine.mjs): `electron/tools/sandbox/engine.mjs`
- [MCP connections](https://github.com/zeraix/zeraix/blob/main/electron/mcp/client.mjs): `electron/mcp/client.mjs`
- [Plugin system](https://github.com/zeraix/zeraix/blob/main/electron/plugins/store.mjs): `electron/plugins/store.mjs`
- [Document skills](https://github.com/zeraix/zeraix/blob/main/src/lib/ai/skills/runtime.ts): `src/lib/ai/skills/runtime.ts`

### Workflow automation

- [Workflow editor](https://github.com/zeraix/zeraix/blob/main/src/app/agent/automation/WorkflowEditor.tsx): `src/app/agent/automation/WorkflowEditor.tsx`
- [Run management](https://github.com/zeraix/zeraix/blob/main/electron/automation/executionManager.mjs): `electron/automation/executionManager.mjs`
- [Workflow data](https://github.com/zeraix/zeraix/blob/main/electron/automation/db.mjs): `electron/automation/db.mjs`

### Other components

- **User**

## Connections

- User → Chat workspace: sends task
- Chat workspace → Turn coordination: starts turn
- Turn coordination → Context builder: prepares context
- Turn coordination → Agent loop: coordinates turn
- Agent loop → Turn runtime: runs turn
- Turn runtime → Context builder: builds model input
- Turn runtime → Cloud model access: requests model
- Model library → Model registry: selects model
- Model registry → Local model manager: manages local models
- Local model manager → Local inference server: starts inference
- Turn runtime → Runtime boundary: dispatches tool calls
- Runtime boundary → Rust Agent Runtime: sends runtime requests
- Rust Agent Runtime → Tool permissions: checks capabilities
- Rust Agent Runtime → File tools: dispatches tools
- File tools → Sandbox execution: runs commands
- Rust Agent Runtime → MCP connections: uses MCP tools
- Turn runtime → Conversation storage: persists conversation
- Workflow editor → Run management: configures and runs
- Run management → Workflow data: records run state
- Agent loop → Document skills: uses skills
- Agent loop → Plugin system: uses extensions
- Chat workspace → Media library: organizes assets
- Chat workspace → Generation services: requests generation
- User → Model library: chooses models
- User → Workflow editor: creates workflows
- User → Skin packages: customizes appearance