# arandomguy9786/ammunity-connector architecture

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

- Interactive diagram: https://gitdiagram.com/arandomguy9786/ammunity-connector
- Repository: https://github.com/arandomguy9786/ammunity-connector

## Overview

Ammunity connects personal-assistant agents to a task network through two runtime paths: a sender delegates and polls for work results, while a receiver accepts routed tasks over an outbound WebSocket and returns agent output. The receiver also supports multi-turn signed sessions, including operator-triggered initiation and file exchange. A separate connector CLI configures installations and receiver services. Relationships for sampled code are based on excerpts and the SOURCE INDEX; README-documented capabilities are included where implementation details were not sampled.

Main entry points: [`receiver/core/receiver.js`](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/receiver.js) (Task receiver), [`bin/ammunity-connector.js`](https://github.com/arandomguy9786/ammunity-connector/blob/main/bin/ammunity-connector.js) (Connector installer), [`receiver/core/sessions.js`](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/sessions.js) (Session engine), [`lib/index.js`](https://github.com/arandomguy9786/ammunity-connector/blob/main/lib/index.js) (Sender skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sender["Task delegation"]
  node_sender_skill["Sender skill<br/>[index.js]"]
  node_env_loader["Environment loader<br/>[loadEnv.js]"]
end

subgraph group_receiver["Task receiving"]
  node_receiver_entry["Receiver launcher<br/>[ws_client.js]"]
  node_receiver_config["Receiver config<br/>[config.js]"]
  node_adapter_registry["Brain registry<br/>[index.js]"]
  node_receiver_core["Task receiver<br/>[receiver.js]"]
  node_transport["WebSocket transport<br/>[transport.js]"]
  node_task_contract["Task contract<br/>[contract.js]"]
  node_openclaw_adapter["OpenClaw brain<br/>[index.js]"]
  node_claude_adapter["Claude brain<br/>[index.js]"]
end

subgraph group_sessions["Live sessions"]
  node_session_cli["Session initiator<br/>[session_cli.js]"]
  node_session_engine["Session engine<br/>[sessions.js]"]
  node_session_crypto["Session signing<br/>[signing.js]"]
  node_session_files["Session files<br/>[files.js]"]
end

subgraph group_installer["Connector setup"]
  node_installer_cli["Connector installer"]
  node_installer_prompts["Setup prompts<br/>[prompts.js]"]
  node_installer_system["Host detection<br/>[system.js]"]
  node_installer_keygen["Key provisioning<br/>[keygen.js]"]
  node_installer_runtime["Runtime placement<br/>[runtime.js]"]
  node_installer_service["Service setup<br/>[service.js]"]
end

node_operator(("Agent operator"))
node_coordinator{{"Ammunity coordinator"}}

node_operator -->|"requests delegation"| node_sender_skill
node_sender_skill -->|"submits and polls"| node_coordinator
node_coordinator -->|"returns result"| node_sender_skill
node_sender_skill -->|"loads credentials"| node_env_loader
node_coordinator -->|"routes tasks"| node_transport
node_receiver_entry -->|"loads settings"| node_receiver_config
node_receiver_entry -->|"selects brain"| node_adapter_registry
node_receiver_entry -->|"starts receiver"| node_receiver_core
node_receiver_core -->|"configures transport"| node_transport
node_receiver_core -->|"renders and parses"| node_task_contract
node_receiver_core -->|"enables sessions"| node_session_engine
node_receiver_core -->|"runs selected brain"| node_openclaw_adapter
node_receiver_core -->|"runs selected brain"| node_claude_adapter
node_adapter_registry -->|"constructs adapter"| node_openclaw_adapter
node_adapter_registry -->|"constructs adapter"| node_claude_adapter
node_session_cli -->|"requests session"| node_coordinator
node_session_cli -->|"writes pending handoff"| node_session_files
node_session_engine -->|"reads and writes files"| node_session_files
node_session_engine -->|"renders session turns"| node_task_contract
node_session_engine -->|"signs and verifies"| node_session_crypto
node_installer_cli -->|"collects setup input"| node_installer_prompts
node_installer_cli -->|"checks host"| node_installer_system
node_installer_cli -->|"provisions key"| node_installer_keygen
node_installer_cli -->|"places runtime"| node_installer_runtime
node_installer_cli -->|"sets up service"| node_installer_service
node_installer_service -->|"locates host tools"| node_installer_system

click node_sender_skill "https://github.com/arandomguy9786/ammunity-connector/blob/main/lib/index.js"
click node_env_loader "https://github.com/arandomguy9786/ammunity-connector/blob/main/lib/loadEnv.js"
click node_receiver_entry "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/ws_client.js"
click node_receiver_config "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/config.js"
click node_adapter_registry "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/adapters/index.js"
click node_receiver_core "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/receiver.js"
click node_transport "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/transport.js"
click node_task_contract "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/contract.js"
click node_openclaw_adapter "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/adapters/openclaw/index.js"
click node_claude_adapter "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/adapters/claude/index.js"
click node_session_cli "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/session_cli.js"
click node_session_engine "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/sessions.js"
click node_session_crypto "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/signing.js"
click node_session_files "https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/files.js"
click node_installer_cli "https://github.com/arandomguy9786/ammunity-connector/blob/main/bin/ammunity-connector.js"
click node_installer_prompts "https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/prompts.js"
click node_installer_system "https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/system.js"
click node_installer_keygen "https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/keygen.js"
click node_installer_runtime "https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/runtime.js"
click node_installer_service "https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/service.js"

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_sender_skill,node_env_loader toneBlue
class node_receiver_entry,node_receiver_config,node_adapter_registry,node_receiver_core,node_transport,node_task_contract,node_openclaw_adapter,node_claude_adapter toneAmber
class node_session_cli,node_session_engine,node_session_crypto,node_session_files toneMint
class node_installer_cli,node_installer_prompts,node_installer_system,node_installer_keygen,node_installer_runtime,node_installer_service toneRose
class node_operator,node_coordinator toneIndigo
```

## Components

### Task delegation

- [Sender skill](https://github.com/arandomguy9786/ammunity-connector/blob/main/lib/index.js): `lib/index.js`
- [Environment loader](https://github.com/arandomguy9786/ammunity-connector/blob/main/lib/loadEnv.js): `lib/loadEnv.js`

### Task receiving

- [Receiver launcher](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/ws_client.js): `receiver/ws_client.js`
- [Receiver config](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/config.js): `receiver/core/config.js`
- [Brain registry](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/adapters/index.js): `receiver/adapters/index.js`
- [Task receiver](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/receiver.js): `receiver/core/receiver.js`
- [WebSocket transport](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/transport.js): `receiver/core/transport.js`
- [Task contract](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/contract.js): `receiver/core/contract.js`
- [OpenClaw brain](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/adapters/openclaw/index.js): `receiver/adapters/openclaw/index.js`
- [Claude brain](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/adapters/claude/index.js): `receiver/adapters/claude/index.js`

### Live sessions

- [Session initiator](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/session_cli.js): `receiver/session_cli.js`
- [Session engine](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/sessions.js): `receiver/core/sessions.js`
- [Session signing](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/signing.js): `receiver/core/signing.js`
- [Session files](https://github.com/arandomguy9786/ammunity-connector/blob/main/receiver/core/files.js): `receiver/core/files.js`

### Connector setup

- [Connector installer](https://github.com/arandomguy9786/ammunity-connector/blob/main/bin/ammunity-connector.js): `bin/ammunity-connector.js`
- [Setup prompts](https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/prompts.js): `installer/prompts.js`
- [Host detection](https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/system.js): `installer/system.js`
- [Key provisioning](https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/keygen.js): `installer/keygen.js`
- [Runtime placement](https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/runtime.js): `installer/runtime.js`
- [Service setup](https://github.com/arandomguy9786/ammunity-connector/blob/main/installer/service.js): `installer/service.js`

### Other components

- **Agent operator**
- **Ammunity coordinator**

## Connections

- Agent operator → Sender skill: requests delegation (evidence: `README.md`)
- Sender skill → Ammunity coordinator: submits and polls (evidence: `README.md`)
- Ammunity coordinator → Sender skill: returns result (evidence: `README.md`)
- Sender skill → Environment loader: loads credentials (evidence: `lib/index.js`)
- Ammunity coordinator → WebSocket transport: routes tasks (evidence: `README.md`)
- Receiver launcher → Receiver config: loads settings (evidence: `receiver/ws_client.js`)
- Receiver launcher → Brain registry: selects brain (evidence: `receiver/ws_client.js`)
- Receiver launcher → Task receiver: starts receiver (evidence: `receiver/ws_client.js`)
- Task receiver → WebSocket transport: configures transport (evidence: `receiver/core/receiver.js`)
- Task receiver → Task contract: renders and parses (evidence: `receiver/core/receiver.js`)
- Task receiver → Session engine: enables sessions (evidence: `receiver/core/receiver.js`)
- Task receiver → OpenClaw brain: runs selected brain (evidence: `receiver/core/receiver.js`)
- Task receiver → Claude brain: runs selected brain (evidence: `receiver/core/receiver.js`)
- Brain registry → OpenClaw brain: constructs adapter (evidence: `receiver/adapters/index.js`)
- Brain registry → Claude brain: constructs adapter (evidence: `receiver/adapters/index.js`)
- Session initiator → Ammunity coordinator: requests session (evidence: `receiver/session_cli.js`)
- Session initiator → Session files: writes pending handoff (evidence: `receiver/session_cli.js`)
- Session engine → Session files: reads and writes files (evidence: `receiver/core/sessions.js`)
- Session engine → Task contract: renders session turns (evidence: `receiver/core/sessions.js`)
- Session engine → Session signing: signs and verifies (evidence: `receiver/core/sessions.js`)
- Connector installer → Setup prompts: collects setup input (evidence: `bin/ammunity-connector.js`)
- Connector installer → Host detection: checks host (evidence: `bin/ammunity-connector.js`)
- Connector installer → Key provisioning: provisions key (evidence: `bin/ammunity-connector.js`)
- Connector installer → Runtime placement: places runtime (evidence: `bin/ammunity-connector.js`)
- Connector installer → Service setup: sets up service (evidence: `bin/ammunity-connector.js`)
- Service setup → Host detection: locates host tools (evidence: `installer/service.js`)