> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openpawz.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> OpenPawz is a Tauri v2 desktop application with a Rust backend and TypeScript frontend.
# Architecture
OpenPawz is a Tauri v2 desktop application with a Rust backend and TypeScript frontend.
## System overview
Views · Feature Modules · IPC Bridge
↕ IPC (invoke / events)
Agent Loop · Providers · Channels · Memory · Skills · Orchestrator · Sandbox
↕
sessions · messages · memories · tasks · skills · agents · projects · trades
## Extensibility — Three-Tier System
Pawz has a three-tier extensibility architecture. Each tier adds more power over the previous.
Custom sidebar views · Dashboard widgets · Persistent data
`pawz-skill.toml` + `[view]` + `[storage]`
Credential vault · API access · CLI binaries · Widgets
`pawz-skill.toml` + `[[credentials]]` + `[instructions]`
Prompt injection only · Zero config · `SKILL.md` format
skills.sh ecosystem · Agent-installable
| Tier | Format | Capabilities |
| --------------- | ---------------------------------------- | ---------------------------------------- |
| **Skill** | `SKILL.md` | Prompt injection, zero config |
| **Integration** | `pawz-skill.toml` | + Credentials, binary detection, widgets |
| **Extension** | `pawz-skill.toml` + `[view]`/`[storage]` | + Custom sidebar views, persistent data |
### Skill loading pipeline
```mermaid actions={false} theme={null}
graph TD
START["Startup"] --> BUILTIN["Load built-in skills\n400+ Rust SkillDefinitions\n+ 25K via MCP Bridge"]
START --> COMMUNITY["Load community SKILL.md\nPer-agent, from DB"]
START --> TOML["Load TOML integrations\n~/.paw/skills/*/pawz-skill.toml"]
START --> EXT["Load extensions\nTOML + view + storage"]
TOML --> T1["Parse credentials\nGenerate UI forms"]
TOML --> T2["Check binaries\nReadiness status"]
TOML --> T3["Register widgets\nDashboard renderer"]
EXT --> E1["Register sidebar views"]
EXT --> E2["Initialize storage namespaces"]
EXT --> E3["Bind view data to storage"]
```
### Agent prompt assembly
```mermaid actions={false} theme={null}
graph TD
SP["System Prompt"] --> P["Core personality\nSOUL.md / agent instructions"]
SP --> BI["Built-in skill instructions"]
SP --> CS["Community Skills\nTier 1, per-agent"]
SP --> INT["Integration instructions + credentials\nTier 2, per-agent"]
SP --> EXT["Extension instructions + credentials\nTier 3, per-agent"]
SP --> CT["Context truncation\nPreserves last user message"]
```
For full details: [Skills](/docs/guides/skills) · [Integrations](/docs/guides/integrations) · [Extensions](/docs/guides/extensions) · [PawzHub](/docs/guides/pawzhub)
## Frontend (`src/`)
Vanilla TypeScript with DOM manipulation — no framework. Each view is a module that renders into the main content area.
### Views
| View | File | Purpose |
| ------------- | ---------------------- | ---------------------------- |
| Today | `views/today/` | Dashboard with quick actions |
| Agents | `views/agents/` | Create, edit, manage agents |
| Tasks | `views/tasks/` | Kanban task board |
| Skills | `views/skills/` | Skill vault management |
| Research | `views/research/` | Research workflow |
| Orchestrator | `views/orchestrator/` | Multi-agent projects |
| Memory Palace | `views/memory-palace/` | Memory browser/search |
| Mail | `views/mail/` | Email integration |
| Trading | `views/trading/` | Trading dashboard |
| Automations | `views/automations/` | Cron task management |
| Settings | `views/settings-*/` | 11 settings tabs |
### Feature modules (`src/features/`)
Atomic design pattern — each feature has `atoms.ts` (data/state), `molecules.ts` (UI components), and `index.ts` (exports).
| Module | Purpose |
| --------------------- | --------------------------------- |
| `agent-policies` | Tool allowlist/denylist per agent |
| `browser-sandbox` | Browser config and network policy |
| `channel-routing` | Message routing rules |
| `container-sandbox` | Docker sandbox config |
| `memory-intelligence` | Memory search and config |
| `prompt-injection` | Injection detection patterns |
| `session-compaction` | Session summarization |
| `slash-commands` | Chat slash command definitions |
### Flow engine (`src/views/flows/`)
The visual workflow builder has its own execution engine built on the Conductor Protocol — an optimizer that detects parallelism, convergence, and higher-dimensional structures in flow graphs.
| Module | Purpose |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `executor.ts` | Main flow executor — graph traversal, memory pre-recall, agent step dispatch |
| `executor-conductor.ts` | Conductor Protocol runtime — parallel execution, tesseract cell dispatch, per-cell memory isolation |
| `executor-atoms.ts` | Shared flow types — `FlowRunState`, `buildNodePrompt()`, `cellMemoryContexts` |
| `conductor-atoms.ts` | Conductor types — `ExecutionUnit`, `ExecutionStrategy`, strategy compilation, `shouldUseConductor()` detection |
| `conductor-tesseract.ts` | Tesseract primitive — cell detection, BFS depth, subgraph building, `findCellSinkNode`, `mergeAtHorizon` |
| `simulation-runtime.ts` | Simulation mirror of the production executor for debug / dry-run mode |
### IPC bridge (`src/engine-bridge.ts`)
All communication with the Rust backend goes through Tauri's `invoke()` and event system. The bridge provides typed wrappers for every engine command.
## Backend (`src-tauri/src/engine/`)
Rust async engine built on Tokio.
### Core modules
| Module | Purpose |
| --------------- | ---------------------------------------------------------------------------------- |
| `agent_loop/` | Agent conversation loop with yield signal and request queue |
| `chat.rs` | System prompt builder, tool assembly, loop detection |
| `state.rs` | Engine state (YieldSignal, RequestQueue, active runs) |
| `providers/` | AI provider factory and routing |
| `channels/` | Channel bridge message handler |
| `memory/` | Hybrid search (BM25 + vector + temporal) |
| `skills/` | Skill catalog and credential vault |
| `orchestrator/` | Multi-agent project execution |
| `sandbox.rs` | Docker container execution |
| `tools/` | Tool dispatch and execution |
| `sessions/` | Session and message persistence |
| `compaction.rs` | Session compaction/summarization |
| `http.rs` | Retry logic, circuit breaker, TLS-pinned client factory, request signing audit log |
| `routing.rs` | Channel-to-agent routing |
| `injection.rs` | Prompt injection detection |
### Channel bridges
Each channel has its own bridge module:
`telegram.rs` · `discord.rs` · `slack.rs` · `matrix.rs` · `irc.rs` · `mattermost.rs` · `nextcloud.rs` · `nostr.rs` · `twitch.rs` · `webchat.rs` · `whatsapp/`
### Provider implementations
| Implementation | Providers |
| ------------------- | --------------------------------------------------------------------- |
| `OpenAiProvider` | OpenAI, Ollama, OpenRouter, DeepSeek, Grok, Mistral, Moonshot, Custom |
| `AnthropicProvider` | Anthropic |
| `GoogleProvider` | Google Gemini |
## Database
Pawz uses **two SQLite databases** — one managed by the Rust engine, one by the TypeScript frontend.
### Engine database (Rust — `rusqlite`)
| Table | Contents |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| `sessions` | Chat sessions per agent (id, label, model, system\_prompt, agent\_id, timestamps) |
| `messages` | All messages with role, content, tool calls JSON, tool\_call\_id, name |
| `engine_config` | Key-value configuration store for engine settings |
| `agent_files` | Agent personality files (SOUL.md, AGENTS.md, etc.) per agent |
| `memories` | Stored facts with embedding vectors, category, importance, timestamps |
| `tasks` | Kanban tasks with title, description, status, priority, cron schedule, model override |
| `task_activity` | Task activity feed (created, assigned, status\_change, agent\_started, etc.) |
| `task_agents` | Multi-agent task assignments (agent\_id, role: lead/collaborator) |
| `projects` | Orchestrator projects with title, goal, status, boss\_agent |
| `project_agents` | Project agent assignments (role, specialty, status, current\_task, model) |
| `project_messages` | Inter-agent messages (delegation, progress, result, error) |
| `trade_history` | Trading records (trade, transfer, dex\_swap) with amounts and status |
| `positions` | Open trading positions with stop-loss/take-profit targets |
| `skill_credentials` | Encrypted API keys and secrets per skill |
| `skill_state` | Enabled/disabled state per skill |
| `skill_custom_instructions` | User-edited skill instructions (overrides defaults) |
| `community_skills` | Installed community skills from skills.sh ecosystem (name, description, instructions, source, enabled) |
### Frontend database (TypeScript — `@tauri-apps/plugin-sql`)
| Table | Contents |
| ------------------------- | ----------------------------------------------------------------------------- |
| `agent_modes` | Chat modes (General, Code Review, Quick Chat) with model, prompt, temperature |
| `projects` | User workspace projects (build, research, create) |
| `project_files` | Files within workspace projects (path, content, language) |
| `automation_runs` | Cron job execution history (job\_id, status, output, error) |
| `research_findings` | Research findings with title, content, source URL |
| `content_documents` | Content Studio documents (markdown, HTML, plaintext) |
| `email_accounts` | Email account configuration (IMAP/SMTP hosts, ports) |
| `emails` | Cached emails with body, read/starred status, agent draft fields |
| `credential_activity_log` | Audit trail for every credential access (action, tool, was\_allowed) |
| `security_audit_log` | Security events (exec\_approval, config\_change, auto\_deny, etc.) |
| `security_rules` | User-defined allow/deny patterns for command execution |
### Canvas database (Rust — `rusqlite`)
| Table | Contents |
| -------------- | ----------------------------------------------------- |
| `canvases` | Canvas workspaces (title, timestamps) |
| `canvas_nodes` | Nodes on a canvas (type, position, size, data) |
| `canvas_edges` | Edges connecting canvas nodes (source, target, label) |
:::info
Sensitive fields in the frontend database are encrypted with AES-256-GCM using a key stored in the OS keychain. Encrypted values are prefixed with `enc:` for identification.
:::
## IPC bridge architecture
All communication between the TypeScript frontend and Rust backend uses Tauri's IPC system. The bridge (`src/engine/molecules/ipc_client.ts`) provides typed wrappers for every invoke command.
### Invoke commands (Frontend → Backend)
Commands are called via `invoke()` and return Promises:
| Category | Commands |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chat** | `engine_chat_send`, `engine_chat_history` |
| **Sessions** | `engine_sessions_list`, `engine_session_rename`, `engine_session_delete`, `engine_session_clear`, `engine_session_compact` |
| **Config** | `engine_get_config`, `engine_set_config`, `engine_upsert_provider`, `engine_remove_provider`, `engine_status`, `engine_auto_setup` |
| **Agent files** | `engine_agent_file_list`, `engine_agent_file_get`, `engine_agent_file_set`, `engine_agent_file_delete` |
| **Memory** | `engine_memory_store`, `engine_memory_search`, `engine_memory_list`, `engine_memory_delete`, `engine_memory_stats`, `engine_get_memory_config`, `engine_set_memory_config`, `engine_test_embedding`, `engine_embedding_status`, `engine_embedding_pull_model`, `engine_ensure_embedding_ready`, `engine_memory_backfill` |
| **Skills** | `engine_skills_list`, `engine_skill_set_enabled`, `engine_skill_set_credential`, `engine_skill_delete_credential`, `engine_skill_revoke_all`, `engine_skill_get_instructions`, `engine_skill_set_instructions` |
| **Community Skills** | `engine_community_skills_list`, `engine_community_skills_browse`, `engine_community_skills_search`, `engine_community_skill_install`, `engine_community_skill_remove`, `engine_community_skill_set_enabled` |
| **Tasks** | `engine_tasks_list`, `engine_task_create`, `engine_task_update`, `engine_task_delete`, `engine_task_move`, `engine_task_activity`, `engine_task_set_agents`, `engine_task_run`, `engine_tasks_cron_tick` |
| **TTS / STT** | `engine_tts_speak`, `engine_tts_get_config`, `engine_tts_set_config`, `engine_tts_transcribe` |
| **Trading** | `engine_trading_history`, `engine_trading_summary`, `engine_trading_policy_get`, `engine_trading_policy_set`, `engine_positions_list`, `engine_position_close`, `engine_position_update_targets` |
| **Projects** | `engine_projects_list`, `engine_project_create`, `engine_project_update`, `engine_project_delete`, `engine_project_set_agents`, `engine_project_messages`, `engine_project_run` |
| **Agents** | `engine_list_all_agents`, `engine_create_agent`, `engine_delete_agent`, `engine_approve_tool` |
| **Browser** | `engine_browser_get_config`, `engine_browser_set_config`, `engine_browser_create_profile`, `engine_browser_delete_profile` |
| **Screenshots** | `engine_screenshots_list`, `engine_screenshot_get`, `engine_screenshot_delete` |
| **Workspaces** | `engine_workspaces_list`, `engine_workspace_files`, `engine_workspace_delete` |
| **Network** | `engine_network_get_policy`, `engine_network_set_policy`, `engine_network_check_url` |
| **Channels** | `engine__start`, `engine__stop`, `engine__status`, `engine__get_config`, `engine__set_config`, `engine__approve_user`, `engine__deny_user`, `engine__remove_user` (for telegram, discord, irc, slack, matrix, mattermost, nextcloud, nostr, twitch) |
| **Tailscale** | `engine_tailscale_status`, `engine_tailscale_get_config`, `engine_tailscale_set_config`, `engine_tailscale_serve_start`, `engine_tailscale_serve_stop`, `engine_tailscale_funnel_start`, `engine_tailscale_funnel_stop`, `engine_tailscale_connect`, `engine_tailscale_disconnect` |
| **Email** | `read_himalaya_config`, `write_himalaya_config`, `remove_himalaya_account`, `fetch_emails`, `fetch_email_content`, `send_email`, `move_email`, `delete_email` |
| **Security** | `get_db_encryption_key` |
### Agent built-in tools
Every agent has access to these built-in tools (defined in `tools.rs`, executed in `tool_executor.rs`):
| Tool | Parameters | Description |
| --------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
| `skill_search` | `query` (string) | Search the skills.sh directory for community skills by keyword |
| `skill_install` | `source` (owner/repo), `path` (skills/id/SKILL.md) | Install a community skill from GitHub |
| `skill_list` | — | List all installed community skills with enabled/disabled status |
These tools allow agents to discover, install, and manage community skills during conversations without requiring the user to visit the Skills tab.
## Events (Backend → Frontend)
The engine communicates with the frontend via Tauri's event system for real-time updates. The frontend subscribes using `listen()` and the backend emits events asynchronously.
| Event | Payload | Purpose |
| ----------------------- | -------------------------------- | ---------------------------------------------------------------------- |
| `engine-event` | `EngineEvent` | Streaming deltas, tool requests, tool results, completions, and errors |
| `project-event` | `{ project_id, agent_id, kind }` | Project/agent finished notifications |
| `agent-profile-updated` | `{ agent_id }` | Agent profile changes (name, avatar, bio) |
### EngineEvent kinds
The `engine-event` payload contains a `kind` field that determines the event type:
| Kind | Fields | Description |
| -------------- | --------------------------------------------- | ------------------------------------------------------- |
| `delta` | `text`, `session_id`, `run_id` | Streaming text chunk from the AI model |
| `tool_request` | `tool_call` (id, function name, arguments) | Agent wants to call a tool — may require human approval |
| `tool_result` | `tool_call_id`, `output`, `success` | Result of a tool execution |
| `complete` | `tool_calls_count`, `usage` (tokens), `model` | Agent turn completed |
| `error` | `message` | Error during agent execution |
### Event flow
```mermaid actions={false} theme={null}
sequenceDiagram
participant U as User
participant FE as Frontend
participant BE as Rust Backend
U->>FE: Send message
FE->>BE: engine_chat_send (invoke)
BE-->>FE: engine-event { delta }
BE-->>FE: engine-event { tool_request }
FE->>BE: engine_approve_tool (if HIL)
BE-->>FE: engine-event { tool_result }
BE-->>FE: engine-event { delta }
BE-->>FE: engine-event { complete }
```
## Build pipeline
Pawz uses a dual build pipeline — **Vite** for the frontend and **Cargo** for the Rust backend, orchestrated by Tauri:
### Development
```bash theme={null}
pnpm tauri dev
```
1. **Vite dev server** starts on `http://localhost:1420` (HMR enabled)
2. **Cargo** compiles the Rust backend in debug mode
3. **Tauri** launches the app window pointing at the Vite dev server
4. File changes in `src/` trigger Vite HMR; changes in `src-tauri/` trigger Cargo rebuild
### Production build
```bash theme={null}
pnpm tauri build
```
1. `pnpm build` — Vite bundles TypeScript → `dist/` (optimized, minified)
2. `cargo build --release` — Compiles Rust backend with optimizations
3. Tauri packages both into a native installer (`.dmg`, `.AppImage`, `.msi`)
### Build configuration
| Config file | Purpose |
| --------------------------- | ----------------------------------------------------------------------------------- |
| `vite.config.ts` | Vite settings: port 1420, ignores `src-tauri/`, HMR on port 1421 |
| `src-tauri/tauri.conf.json` | Tauri settings: `beforeDevCommand`, `beforeBuildCommand`, CSP policy, window config |
| `src-tauri/Cargo.toml` | Rust dependencies and build profile |
| `tsconfig.json` | TypeScript compiler options |
### Content Security Policy
The production CSP restricts the frontend:
```
default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
connect-src 'self' ws://127.0.0.1:* https://127.0.0.1:*;
img-src 'self' data: blob:; font-src 'self' data:;
object-src 'none'; frame-ancestors 'none'
```
## Technology stack
| Layer | Technology |
| ---------------- | ------------------------------------------- |
| Shell | Tauri v2 |
| Frontend | TypeScript, vanilla DOM |
| Backend | Rust, Tokio async |
| Database | SQLite (rusqlite + @tauri-apps/plugin-sql) |
| HTTP | reqwest |
| Browser | headless\_chrome (Chrome DevTools Protocol) |
| HTML parsing | scraper (Rust) |
| Docker | bollard |
| Build (frontend) | Vite |
| Build (backend) | Cargo |
| Icons | Material Symbols Outlined |
| Fonts | Inter, JetBrains Mono |