# aaswordman/operit2 architecture

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

- Interactive diagram: https://gitdiagram.com/aaswordman/operit2
- Repository: https://github.com/aaswordman/operit2

## Overview

Operit2 is a cross-device personal Agent: a user starts a conversation or task on a CoreNode, whose Core coordinates model requests and Host capabilities; results and persisted context can then be synchronized for continuation on another node. The repository also includes CLI/TUI and Flutter access surfaces, extension runtimes, data migration, and ESP32 edge services. The README documents several architectural relationships and capabilities that were not sampled in source; those links are cited to the README rather than implying inspection of unsampled implementations.

Main entry points: [`core/crates/runtime/application`](https://github.com/aaswordman/operit2/tree/main/core/crates/runtime/application) (Core runtime), [`apps/cli/src/cli/mod.rs`](https://github.com/aaswordman/operit2/blob/main/apps/cli/src/cli/mod.rs) (CLI operations), [`apps/cli/src/main.rs`](https://github.com/aaswordman/operit2/blob/main/apps/cli/src/main.rs) (CLI entry), [`apps/cli/src/cli/link.rs`](https://github.com/aaswordman/operit2/blob/main/apps/cli/src/cli/link.rs) (Link commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access surfaces"]
  node_cli_entry["CLI entry<br/>[main.rs]"]
  node_cli_commands["CLI operations<br/>[mod.rs]"]
  node_tui["Terminal UI<br/>[app.rs]"]
  node_flutter["Flutter app"]
end

subgraph group_agent["Agent runtime"]
  node_core_runtime["Core runtime"]
  node_core_proxy["Local Core proxy<br/>[core_proxy.rs]"]
  node_provider["Model providers"]
  node_local_models["Local model install"]
  node_storage[("Runtime persistence")]
  node_backup["Backup and migration<br/>[storage.rs]"]
end

subgraph group_network["Device collaboration"]
  node_link_cli["Link commands<br/>[link.rs]"]
  node_discovery["Peer discovery"]
  node_peer_transport["PeerLink transport"]
  node_space["Space sync"]
end

subgraph group_extensions["Extensions"]
  node_js_engine["JavaScript runtime<br/>[JsEngine.rs]"]
  node_skills["Skill manager<br/>[SkillManager.rs]"]
  node_workflow["Workflow package<br/>[engine.ts]"]
  node_worldbook["Worldbook package<br/>[main.ts]"]
end

subgraph group_platforms["Platform capabilities"]
  node_host["Host capabilities"]
  node_esp32["ESP32 edge node<br/>[main.rs]"]
end

node_user(("Personal user"))
node_external_model(("Model service"))

node_user -->|"starts task"| node_cli_entry
node_cli_entry -->|"routes CLI"| node_cli_commands
node_cli_entry -->|"routes TUI"| node_tui
node_cli_commands -->|"creates local Core"| node_core_proxy
node_tui -->|"uses Core proxy"| node_core_proxy
node_flutter -->|"hosts CoreNode"| node_core_runtime
node_core_proxy -->|"calls runtime"| node_core_runtime
node_core_runtime -->|"uses capabilities"| node_host
node_core_runtime -->|"requests model"| node_provider
node_provider -.->|"calls service"| node_external_model
node_local_models -->|"downloads via Host"| node_host
node_core_runtime -->|"persists state"| node_storage
node_cli_commands -->|"exports and restores"| node_backup
node_cli_commands -->|"offers link commands"| node_link_cli
node_link_cli -->|"discovers peers"| node_discovery
node_link_cli -->|"connects nodes"| node_peer_transport
node_peer_transport -->|"carries sync traffic"| node_space
node_space -->|"syncs records"| node_storage
node_core_runtime -.->|"runs extensions"| node_js_engine
node_core_runtime -->|"loads skills"| node_skills
node_js_engine -.->|"executes package"| node_workflow
node_js_engine -.->|"executes package"| node_worldbook
node_esp32 -->|"provides edge capability"| node_host

click node_cli_entry "https://github.com/aaswordman/operit2/blob/main/apps/cli/src/main.rs"
click node_cli_commands "https://github.com/aaswordman/operit2/blob/main/apps/cli/src/cli/mod.rs"
click node_tui "https://github.com/aaswordman/operit2/blob/main/apps/cli/src/tui/core/app.rs"
click node_flutter "https://github.com/aaswordman/operit2/tree/main/apps/flutter/app"
click node_core_runtime "https://github.com/aaswordman/operit2/tree/main/core/crates/runtime/application"
click node_core_proxy "https://github.com/aaswordman/operit2/blob/main/apps/cli/src/core_proxy.rs"
click node_provider "https://github.com/aaswordman/operit2/tree/main/core/crates/provider"
click node_local_models "https://github.com/aaswordman/operit2/blob/main/core/crates/provider/local-model/src/LocalEngineDownload.rs"
click node_host "https://github.com/aaswordman/operit2/tree/main/hosts"
click node_storage "https://github.com/aaswordman/operit2/blob/main/core/crates/persistence/store/src/RuntimeStorageHost.rs"
click node_backup "https://github.com/aaswordman/operit2/blob/main/core/crates/command/core/src/commands/storage.rs"
click node_link_cli "https://github.com/aaswordman/operit2/blob/main/apps/cli/src/cli/link.rs"
click node_discovery "https://github.com/aaswordman/operit2/blob/main/hosts/common/operit-host-native-common/src/ServiceDiscovery.rs"
click node_peer_transport "https://github.com/aaswordman/operit2/tree/main/core/crates"
click node_space "https://github.com/aaswordman/operit2/tree/main/core/crates"
click node_js_engine "https://github.com/aaswordman/operit2/blob/main/core/crates/plugin/javascript-bridge/src/javascript/JsEngine.rs"
click node_skills "https://github.com/aaswordman/operit2/blob/main/core/crates/tool/services/src/tools/skill/SkillManager.rs"
click node_workflow "https://github.com/aaswordman/operit2/blob/main/plugins/packages/buildin/workflow/src/engine.ts"
click node_worldbook "https://github.com/aaswordman/operit2/blob/main/plugins/packages/external/worldbook/src/main.ts"
click node_esp32 "https://github.com/aaswordman/operit2/blob/main/apps/esp32/src/main.rs"

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_cli_entry,node_cli_commands,node_tui,node_flutter,node_user toneBlue
class node_core_runtime,node_core_proxy,node_provider,node_local_models,node_storage,node_backup toneAmber
class node_link_cli,node_discovery,node_peer_transport,node_space toneMint
class node_js_engine,node_skills,node_workflow,node_worldbook toneRose
class node_host,node_esp32,node_external_model toneIndigo
```

## Components

### Access surfaces

- [CLI entry](https://github.com/aaswordman/operit2/blob/main/apps/cli/src/main.rs): `apps/cli/src/main.rs`
- [CLI operations](https://github.com/aaswordman/operit2/blob/main/apps/cli/src/cli/mod.rs): `apps/cli/src/cli/mod.rs`
- [Terminal UI](https://github.com/aaswordman/operit2/blob/main/apps/cli/src/tui/core/app.rs): `apps/cli/src/tui/core/app.rs`
- [Flutter app](https://github.com/aaswordman/operit2/tree/main/apps/flutter/app): `apps/flutter/app`

### Agent runtime

- [Core runtime](https://github.com/aaswordman/operit2/tree/main/core/crates/runtime/application): `core/crates/runtime/application`
- [Local Core proxy](https://github.com/aaswordman/operit2/blob/main/apps/cli/src/core_proxy.rs): `apps/cli/src/core_proxy.rs`
- [Model providers](https://github.com/aaswordman/operit2/tree/main/core/crates/provider): `core/crates/provider`
- [Local model install](https://github.com/aaswordman/operit2/blob/main/core/crates/provider/local-model/src/LocalEngineDownload.rs): `core/crates/provider/local-model/src/LocalEngineDownload.rs`
- [Runtime persistence](https://github.com/aaswordman/operit2/blob/main/core/crates/persistence/store/src/RuntimeStorageHost.rs): `core/crates/persistence/store/src/RuntimeStorageHost.rs`
- [Backup and migration](https://github.com/aaswordman/operit2/blob/main/core/crates/command/core/src/commands/storage.rs): `core/crates/command/core/src/commands/storage.rs`

### Device collaboration

- [Link commands](https://github.com/aaswordman/operit2/blob/main/apps/cli/src/cli/link.rs): `apps/cli/src/cli/link.rs`
- [Peer discovery](https://github.com/aaswordman/operit2/blob/main/hosts/common/operit-host-native-common/src/ServiceDiscovery.rs): `hosts/common/operit-host-native-common/src/ServiceDiscovery.rs`
- [PeerLink transport](https://github.com/aaswordman/operit2/tree/main/core/crates): `core/crates`
- [Space sync](https://github.com/aaswordman/operit2/tree/main/core/crates): `core/crates`

### Extensions

- [JavaScript runtime](https://github.com/aaswordman/operit2/blob/main/core/crates/plugin/javascript-bridge/src/javascript/JsEngine.rs): `core/crates/plugin/javascript-bridge/src/javascript/JsEngine.rs`
- [Skill manager](https://github.com/aaswordman/operit2/blob/main/core/crates/tool/services/src/tools/skill/SkillManager.rs): `core/crates/tool/services/src/tools/skill/SkillManager.rs`
- [Workflow package](https://github.com/aaswordman/operit2/blob/main/plugins/packages/buildin/workflow/src/engine.ts): `plugins/packages/buildin/workflow/src/engine.ts`
- [Worldbook package](https://github.com/aaswordman/operit2/blob/main/plugins/packages/external/worldbook/src/main.ts): `plugins/packages/external/worldbook/src/main.ts`

### Platform capabilities

- [Host capabilities](https://github.com/aaswordman/operit2/tree/main/hosts): `hosts`
- [ESP32 edge node](https://github.com/aaswordman/operit2/blob/main/apps/esp32/src/main.rs): `apps/esp32/src/main.rs`

### Other components

- **Personal user**
- **Model service**

## Connections

- Personal user → CLI entry: starts task (evidence: `apps/cli/src/main.rs`)
- CLI entry → CLI operations: routes CLI (evidence: `apps/cli/src/main.rs`)
- CLI entry → Terminal UI: routes TUI (evidence: `apps/cli/src/main.rs`)
- CLI operations → Local Core proxy: creates local Core (evidence: `apps/cli/src/cli/mod.rs`)
- Terminal UI → Local Core proxy: uses Core proxy (evidence: `apps/cli/src/tui/core/app.rs`)
- Flutter app → Core runtime: hosts CoreNode (evidence: `README.md`)
- Local Core proxy → Core runtime: calls runtime (evidence: `apps/cli/src/core_proxy.rs`)
- Core runtime → Host capabilities: uses capabilities (evidence: `README.md`)
- Core runtime → Model providers: requests model (evidence: `README.md`)
- Model providers → Model service: calls service
- Local model install → Host capabilities: downloads via Host (evidence: `core/crates/provider/local-model/src/LocalEngineDownload.rs`)
- Core runtime → Runtime persistence: persists state (evidence: `README.md`)
- CLI operations → Backup and migration: exports and restores (evidence: `apps/cli/src/cli/mod.rs`)
- CLI operations → Link commands: offers link commands (evidence: `apps/cli/src/cli/mod.rs`)
- Link commands → Peer discovery: discovers peers (evidence: `README.md`)
- Link commands → PeerLink transport: connects nodes (evidence: `README.md`)
- PeerLink transport → Space sync: carries sync traffic (evidence: `README.md`)
- Space sync → Runtime persistence: syncs records (evidence: `README.md`)
- Core runtime → JavaScript runtime: runs extensions
- Core runtime → Skill manager: loads skills (evidence: `core/crates/tool/services/src/tools/skill/SkillManager.rs`)
- JavaScript runtime → Workflow package: executes package
- JavaScript runtime → Worldbook package: executes package
- ESP32 edge node → Host capabilities: provides edge capability (evidence: `README.md`)
