# g9000/animaos-swarm architecture

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

- Interactive diagram: https://gitdiagram.com/g9000/animaos-swarm
- Repository: https://github.com/g9000/animaos-swarm

## Overview

AnimaOS-SWARM is a personal AI companion whose primary workflow is a user conversing in the web app, which uses the TypeScript SDK to reach the Rust daemon; the daemon runs agent tasks and returns live events and session history. The repository also documents memory, connected tools, delegated helpers, approvals, workspace management, and scheduled jobs as product capabilities. Several links below rely on README statements or the source index; unsampled implementation details are represented at subsystem level rather than inferred as specific calls.

Main entry points: [`hosts/rust-daemon/src/app.rs`](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/app.rs) (Rust Daemon), [`packages/core-rust/crates/anima-core/src/engine.rs`](https://github.com/g9000/animaos-swarm/blob/main/packages/core-rust/crates/anima-core/src/engine.rs) (Agent Runtime Core), [`apps/web/src/hooks/useLiveSession.ts`](https://github.com/g9000/animaos-swarm/blob/main/apps/web/src/hooks/useLiveSession.ts) (Live Session), [`apps/web/src/ViewHarness.tsx`](https://github.com/g9000/animaos-swarm/blob/main/apps/web/src/ViewHarness.tsx) (Companion Web)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_companion["Companion UI"]
  node_web["Companion Web<br/>[ViewHarness.tsx]"]
  node_live["Live Session<br/>[useLiveSession.ts]"]
end

subgraph group_boundary["Client Boundary"]
  node_sdk["TypeScript SDK<br/>[client.ts]"]
end

subgraph group_runtime["Daemon Runtime"]
  node_daemon["Rust Daemon<br/>[app.rs]"]
  node_http["HTTP Routes<br/>[http.rs]"]
  node_runs["Agent Runs<br/>[agent_runs.rs]"]
  node_core["Agent Runtime Core<br/>[engine.rs]"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_models["Model Adapters<br/>[adapter.rs]"]
  node_tools["Agent Tools<br/>[tools.rs]"]
  node_memory["Workspace Memory<br/>[memory_manager.rs]"]
  node_swarm["Delegated Helpers<br/>[coordinator.rs]"]
  node_connectors["Connected Services<br/>[runtime.rs]"]
  node_approvals["Approval Gates<br/>[gate.rs]"]
  node_jobs["Scheduled Jobs<br/>[jobs.rs]"]
end

subgraph group_persistence["State and History"]
  node_history[("Session History<br/>[mod.rs]")]
  node_state[("Daemon State<br/>[state.rs]")]
end

node_user(("Companion User"))

node_user -->|"starts conversation"| node_web
node_web -.->|"opens session"| node_live
node_live -->|"requests and subscribes"| node_sdk
node_sdk -->|"HTTP and SSE"| node_daemon
node_daemon -->|"routes requests"| node_http
node_daemon -->|"hosts run service"| node_runs
node_runs -.->|"executes tasks"| node_core
node_core -.->|"requests inference"| node_models
node_core -.->|"invokes tools"| node_tools
node_core -.->|"uses memory"| node_memory
node_core -.->|"delegates helpers"| node_swarm
node_daemon -->|"hosts integrations"| node_connectors
node_daemon -.->|"enforces approvals"| node_approvals
node_daemon -.->|"runs scheduled work"| node_jobs
node_daemon -->|"maintains state"| node_state
node_state -->|"persists messages and runs"| node_history
node_history -.->|"serves session history"| node_live

click node_web "https://github.com/g9000/animaos-swarm/blob/main/apps/web/src/ViewHarness.tsx"
click node_live "https://github.com/g9000/animaos-swarm/blob/main/apps/web/src/hooks/useLiveSession.ts"
click node_sdk "https://github.com/g9000/animaos-swarm/blob/main/packages/sdk/src/client.ts"
click node_daemon "https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/app.rs"
click node_http "https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/routes/http.rs"
click node_runs "https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/agent_runs.rs"
click node_core "https://github.com/g9000/animaos-swarm/blob/main/packages/core-rust/crates/anima-core/src/engine.rs"
click node_models "https://github.com/g9000/animaos-swarm/blob/main/packages/core-rust/crates/anima-model-adapters/src/adapter.rs"
click node_tools "https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/tools.rs"
click node_memory "https://github.com/g9000/animaos-swarm/blob/main/packages/core-rust/crates/anima-memory/src/memory_manager.rs"
click node_swarm "https://github.com/g9000/animaos-swarm/blob/main/packages/core-rust/crates/anima-swarm/src/coordinator.rs"
click node_connectors "https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/connectors/runtime.rs"
click node_approvals "https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/approvals/gate.rs"
click node_jobs "https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/jobs.rs"
click node_history "https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/history/mod.rs"
click node_state "https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/state.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_web,node_live,node_user toneBlue
class node_sdk toneAmber
class node_daemon,node_http,node_runs,node_core toneMint
class node_models,node_tools,node_memory,node_swarm,node_connectors,node_approvals,node_jobs toneRose
class node_history,node_state toneIndigo
```

## Components

### Companion UI

- [Companion Web](https://github.com/g9000/animaos-swarm/blob/main/apps/web/src/ViewHarness.tsx): `apps/web/src/ViewHarness.tsx`
- [Live Session](https://github.com/g9000/animaos-swarm/blob/main/apps/web/src/hooks/useLiveSession.ts): `apps/web/src/hooks/useLiveSession.ts`

### Client Boundary

- [TypeScript SDK](https://github.com/g9000/animaos-swarm/blob/main/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`

### Daemon Runtime

- [Rust Daemon](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/app.rs): `hosts/rust-daemon/src/app.rs`
- [HTTP Routes](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/routes/http.rs): `hosts/rust-daemon/src/routes/http.rs`
- [Agent Runs](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/agent_runs.rs): `hosts/rust-daemon/src/agent_runs.rs`
- [Agent Runtime Core](https://github.com/g9000/animaos-swarm/blob/main/packages/core-rust/crates/anima-core/src/engine.rs): `packages/core-rust/crates/anima-core/src/engine.rs`

### Agent Capabilities

- [Model Adapters](https://github.com/g9000/animaos-swarm/blob/main/packages/core-rust/crates/anima-model-adapters/src/adapter.rs): `packages/core-rust/crates/anima-model-adapters/src/adapter.rs`
- [Agent Tools](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/tools.rs): `hosts/rust-daemon/src/tools.rs`
- [Workspace Memory](https://github.com/g9000/animaos-swarm/blob/main/packages/core-rust/crates/anima-memory/src/memory_manager.rs): `packages/core-rust/crates/anima-memory/src/memory_manager.rs`
- [Delegated Helpers](https://github.com/g9000/animaos-swarm/blob/main/packages/core-rust/crates/anima-swarm/src/coordinator.rs): `packages/core-rust/crates/anima-swarm/src/coordinator.rs`
- [Connected Services](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/connectors/runtime.rs): `hosts/rust-daemon/src/connectors/runtime.rs`
- [Approval Gates](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/approvals/gate.rs): `hosts/rust-daemon/src/approvals/gate.rs`
- [Scheduled Jobs](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/jobs.rs): `hosts/rust-daemon/src/jobs.rs`

### State and History

- [Session History](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/history/mod.rs): `hosts/rust-daemon/src/history/mod.rs`
- [Daemon State](https://github.com/g9000/animaos-swarm/blob/main/hosts/rust-daemon/src/state.rs): `hosts/rust-daemon/src/state.rs`

### Other components

- **Companion User**

## Connections

- Companion User → Companion Web: starts conversation (evidence: `README.md`)
- Companion Web → Live Session: opens session
- Live Session → TypeScript SDK: requests and subscribes (evidence: `apps/web/src/hooks/useLiveSession.ts`)
- TypeScript SDK → Rust Daemon: HTTP and SSE (evidence: `README.md`)
- Rust Daemon → HTTP Routes: routes requests (evidence: `hosts/rust-daemon/src/app.rs`)
- Rust Daemon → Agent Runs: hosts run service (evidence: `hosts/rust-daemon/src/app.rs`)
- Agent Runs → Agent Runtime Core: executes tasks
- Agent Runtime Core → Model Adapters: requests inference
- Agent Runtime Core → Agent Tools: invokes tools
- Agent Runtime Core → Workspace Memory: uses memory
- Agent Runtime Core → Delegated Helpers: delegates helpers
- Rust Daemon → Connected Services: hosts integrations (evidence: `README.md`)
- Rust Daemon → Approval Gates: enforces approvals
- Rust Daemon → Scheduled Jobs: runs scheduled work (evidence: `hosts/rust-daemon/src/app.rs`)
- Rust Daemon → Daemon State: maintains state (evidence: `hosts/rust-daemon/src/app.rs`)
- Daemon State → Session History: persists messages and runs (evidence: `hosts/rust-daemon/src/history/mod.rs`)
- Session History → Live Session: serves session history
