# ace-haxxed/atomic architecture

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

- Interactive diagram: https://gitdiagram.com/ace-haxxed/atomic
- Repository: https://github.com/ace-haxxed/atomic
- Video tour (about a minute): https://gitdiagram.com/ace-haxxed/atomic/video

## Overview

Atomic is a local-first desktop AI assistant with Chat, Cowork, and Code modes sharing one streaming agent runtime. The user selects a mode and model, submits a conversation, and receives streamed responses; tool calls pass through permission checks and approval before execution. The React shell uses the host-agnostic LocalHost, composed with Tauri-provided platform, keychain, SQLite, and app-directory services. Core capabilities also include model discovery and selection, settings, audit and conversation persistence, and workspace tools. Source excerpts and index references support the main runtime links; unsampled subsystem links are omitted where their callers are not shown.

Main entry points: [`packages/core/src/host/local.ts`](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/host/local.ts) (LocalHost), [`packages/core/src/agent/loop.ts`](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/agent/loop.ts) (Agent loop), [`packages/core/src/providers/registry.ts`](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/providers/registry.ts) (Provider registry), [`apps/desktop/src/app/app.tsx`](https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/app/app.tsx) (React app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_app["React app<br/>[app.tsx]"]
  node_run_hook["Agent run hook<br/>[use-agent-run.ts]"]
  node_message_view["Message view<br/>[message-list.tsx]"]
  node_settings_ui["Settings UI<br/>[settings-panel.tsx]"]
  node_bootstrap["Desktop composition<br/>[bootstrap.ts]"]
  node_tauri["Tauri host<br/>[lib.rs]"]
end

subgraph group_runtime["Agent runtime"]
  node_local_host["LocalHost<br/>[local.ts]"]
  node_agent_loop["Agent loop<br/>[loop.ts]"]
  node_tool_registry["Tool registry<br/>[registry.ts]"]
  node_workspace_tools["Workspace tools<br/>[index.ts]"]
end

subgraph group_models["Models and providers"]
  node_catalog_service["Model catalog<br/>[catalog-service.ts]"]
  node_provider_registry["Provider registry<br/>[registry.ts]"]
  node_zen["Zen provider<br/>[provider.ts]"]
  node_ollama["Ollama provider<br/>[provider.ts]"]
  node_http["Provider HTTP<br/>[http.ts]"]
  node_model_service["Model service<br/>[provider.ts]"]
end

subgraph group_data["Local data and policy"]
  node_permission_gate["Permission gate<br/>[gate.ts]"]
  node_settings["Settings schema<br/>[schema.ts]"]
  node_audit["Audit log<br/>[audit-log.ts]"]
  node_repositories["Repositories<br/>[repositories.ts]"]
  node_database[("SQLite database<br/>[database.ts]")]
end

node_user(("User"))
node_keychain[("OS keychain")]

node_user -->|"interacts with"| node_app
node_app -->|"starts runs"| node_run_hook
node_run_hook -.->|"requests stream"| node_local_host
node_local_host -->|"runs agent"| node_agent_loop
node_agent_loop -->|"streams completion"| node_model_service
node_agent_loop -->|"dispatches tools"| node_tool_registry
node_agent_loop -->|"checks calls"| node_permission_gate
node_agent_loop -.->|"records calls"| node_audit
node_permission_gate -->|"reads policy"| node_settings
node_tool_registry -.->|"registers tools"| node_workspace_tools
node_agent_loop -.->|"streams events"| node_message_view
node_app -->|"resolves model"| node_catalog_service
node_settings_ui -.->|"configures host"| node_local_host
node_catalog_service -->|"looks up providers"| node_provider_registry
node_local_host -->|"selects provider"| node_provider_registry
node_provider_registry -->|"creates provider"| node_zen
node_provider_registry -.->|"creates provider"| node_ollama
node_zen -->|"sends requests"| node_http
node_ollama -->|"sends requests"| node_http
node_zen -->|"implements provider"| node_model_service
node_ollama -->|"implements provider"| node_model_service
node_bootstrap -.->|"composes host"| node_local_host
node_bootstrap -.->|"uses native services"| node_tauri
node_tauri -.->|"stores secrets"| node_keychain
node_local_host -.->|"persists data"| node_repositories
node_repositories -.->|"uses database port"| node_database
node_local_host -.->|"uses settings"| node_settings

click node_app "https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/app/app.tsx"
click node_run_hook "https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/app/use-agent-run.ts"
click node_message_view "https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/components/message-list.tsx"
click node_settings_ui "https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/components/settings-panel.tsx"
click node_bootstrap "https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/lib/bootstrap.ts"
click node_tauri "https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src-tauri/src/lib.rs"
click node_local_host "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/host/local.ts"
click node_agent_loop "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/agent/loop.ts"
click node_tool_registry "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/tools/registry.ts"
click node_permission_gate "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/permissions/gate.ts"
click node_settings "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/settings/schema.ts"
click node_audit "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/audit/audit-log.ts"
click node_repositories "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/storage/repositories.ts"
click node_database "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/storage/database.ts"
click node_catalog_service "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/models/catalog-service.ts"
click node_provider_registry "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/providers/registry.ts"
click node_zen "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/providers/zen/provider.ts"
click node_ollama "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/providers/ollama/provider.ts"
click node_http "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/providers/http.ts"
click node_model_service "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/models/provider.ts"
click node_workspace_tools "https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/tools/index.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_app,node_run_hook,node_message_view,node_settings_ui,node_bootstrap,node_tauri,node_user toneBlue
class node_local_host,node_agent_loop,node_tool_registry,node_workspace_tools,node_keychain toneAmber
class node_catalog_service,node_provider_registry,node_zen,node_ollama,node_http,node_model_service toneMint
class node_permission_gate,node_settings,node_audit,node_repositories,node_database toneRose
```

## Components

### Desktop app

- [React app](https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/app/app.tsx): `apps/desktop/src/app/app.tsx`
- [Agent run hook](https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/app/use-agent-run.ts): `apps/desktop/src/app/use-agent-run.ts`
- [Message view](https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/components/message-list.tsx): `apps/desktop/src/components/message-list.tsx`
- [Settings UI](https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/components/settings-panel.tsx): `apps/desktop/src/components/settings-panel.tsx`
- [Desktop composition](https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src/lib/bootstrap.ts): `apps/desktop/src/lib/bootstrap.ts`
- [Tauri host](https://github.com/ace-haxxed/atomic/blob/master/apps/desktop/src-tauri/src/lib.rs): `apps/desktop/src-tauri/src/lib.rs`

### Agent runtime

- [LocalHost](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/host/local.ts): `packages/core/src/host/local.ts`
- [Agent loop](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/agent/loop.ts): `packages/core/src/agent/loop.ts`
- [Tool registry](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/tools/registry.ts): `packages/core/src/tools/registry.ts`
- [Workspace tools](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/tools/index.ts): `packages/core/src/tools/index.ts`

### Models and providers

- [Model catalog](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/models/catalog-service.ts): `packages/core/src/models/catalog-service.ts`
- [Provider registry](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/providers/registry.ts): `packages/core/src/providers/registry.ts`
- [Zen provider](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/providers/zen/provider.ts): `packages/core/src/providers/zen/provider.ts`
- [Ollama provider](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/providers/ollama/provider.ts): `packages/core/src/providers/ollama/provider.ts`
- [Provider HTTP](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/providers/http.ts): `packages/core/src/providers/http.ts`
- [Model service](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/models/provider.ts): `packages/core/src/models/provider.ts`

### Local data and policy

- [Permission gate](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/permissions/gate.ts): `packages/core/src/permissions/gate.ts`
- [Settings schema](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/settings/schema.ts): `packages/core/src/settings/schema.ts`
- [Audit log](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/audit/audit-log.ts): `packages/core/src/audit/audit-log.ts`
- [Repositories](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/storage/repositories.ts): `packages/core/src/storage/repositories.ts`
- [SQLite database](https://github.com/ace-haxxed/atomic/blob/master/packages/core/src/storage/database.ts): `packages/core/src/storage/database.ts`

### Other components

- **User**
- **OS keychain**

## Connections

- User → React app: interacts with (evidence: `apps/desktop/src/app/app.tsx`)
- React app → Agent run hook: starts runs (evidence: `apps/desktop/src/app/app.tsx`)
- Agent run hook → LocalHost: requests stream
- LocalHost → Agent loop: runs agent (evidence: `packages/core/src/host/local.ts`)
- Agent loop → Model service: streams completion (evidence: `packages/core/src/agent/loop.ts`)
- Agent loop → Tool registry: dispatches tools (evidence: `packages/core/src/agent/loop.ts`)
- Agent loop → Permission gate: checks calls (evidence: `packages/core/src/agent/loop.ts`)
- Agent loop → Audit log: records calls
- Permission gate → Settings schema: reads policy (evidence: `packages/core/src/permissions/gate.ts`)
- Tool registry → Workspace tools: registers tools
- Agent loop → Message view: streams events
- React app → Model catalog: resolves model (evidence: `apps/desktop/src/app/app.tsx`)
- Settings UI → LocalHost: configures host
- Model catalog → Provider registry: looks up providers (evidence: `packages/core/src/models/catalog-service.ts`)
- LocalHost → Provider registry: selects provider (evidence: `packages/core/src/host/local.ts`)
- Provider registry → Zen provider: creates provider (evidence: `packages/core/src/providers/registry.ts`)
- Provider registry → Ollama provider: creates provider
- Zen provider → Provider HTTP: sends requests (evidence: `packages/core/src/providers/zen/provider.ts`)
- Ollama provider → Provider HTTP: sends requests (evidence: `packages/core/src/providers/ollama/provider.ts`)
- Zen provider → Model service: implements provider (evidence: `packages/core/src/providers/zen/provider.ts`)
- Ollama provider → Model service: implements provider (evidence: `packages/core/src/providers/ollama/provider.ts`)
- Desktop composition → LocalHost: composes host
- Desktop composition → Tauri host: uses native services
- Tauri host → OS keychain: stores secrets
- LocalHost → Repositories: persists data (evidence: `packages/core/src/host/local.ts`)
- Repositories → SQLite database: uses database port
- LocalHost → Settings schema: uses settings (evidence: `packages/core/src/host/local.ts`)