# alexrudloff/clawchat architecture

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

- Interactive diagram: https://gitdiagram.com/alexrudloff/clawchat
- Repository: https://github.com/alexrudloff/clawchat

## Overview

ClawChat is a peer-to-peer encrypted messaging gateway for agents on different machines. Agents invoke the CLI, which communicates with a local daemon; the daemon selects an identity, routes messages, and sends them over authenticated libp2p sessions to remote gateways. Those gateways deliver messages to their own identities. The README also documents multi-identity isolation, peer exchange, NAT traversal, per-identity access controls, and OpenClaw wake configuration. Some subsystem wiring is supported only by README or source-index references; the graph omits uncertain links.

Main entry points: [`src/daemon/server.ts`](https://github.com/alexrudloff/clawchat/blob/main/src/daemon/server.ts) (Gateway Daemon), [`src/identity/keys.ts`](https://github.com/alexrudloff/clawchat/blob/main/src/identity/keys.ts) (Identity and Attestation), [`src/net/session.ts`](https://github.com/alexrudloff/clawchat/blob/main/src/net/session.ts) (Encrypted Session), [`src/cli.ts`](https://github.com/alexrudloff/clawchat/blob/main/src/cli.ts) (CLI Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Local Client"]
  node_cli["CLI Commands<br/>[cli.ts]"]
  node_gateway_cli["Gateway Setup<br/>[gateway.ts]"]
end

subgraph group_gateway["Gateway Runtime"]
  node_daemon["Gateway Daemon<br/>[server.ts]"]
  node_router["Message Routing<br/>[message-router.ts]"]
end

subgraph group_identity["Identity and Policy"]
  node_identity_manager["Identity Runtime"]
  node_config["Gateway Configuration<br/>[gateway-config.ts]"]
  node_identity_keys["Identity and Attestation<br/>[keys.ts]"]
  node_wallet["Stacks Wallet<br/>[wallet.ts]"]
  node_policy["Identity ACL and Wake<br/>[gateway.ts]"]
end

subgraph group_transport["P2P Transport"]
  node_libp2p["Libp2p Node<br/>[libp2p-node.ts]"]
  node_protocol["SNaP2P Authentication<br/>[snap2p-protocol.ts]"]
  node_session["Encrypted Session<br/>[session.ts]"]
  node_noise["Noise Encryption<br/>[noise.ts]"]
  node_framing["Wire Framing<br/>[framing.ts]"]
  node_px1["PX-1 Peer Exchange<br/>[px1.ts]"]
end

node_agent(("Agent"))
node_remote(("Remote Gateway"))

node_agent -->|"invokes"| node_cli
node_cli -->|"uses IPC"| node_daemon
node_gateway_cli -->|"configures"| node_config
node_cli -->|"calls commands"| node_daemon
node_daemon -->|"loads"| node_config
node_daemon -->|"manages identities"| node_identity_manager
node_daemon -->|"routes messages"| node_router
node_identity_manager -->|"loads identity"| node_identity_keys
node_identity_keys -->|"derives wallet"| node_wallet
node_config -->|"defines settings"| node_policy
node_daemon -->|"starts node"| node_libp2p
node_daemon -->|"starts handler"| node_protocol
node_daemon -->|"exchanges peers"| node_px1
node_libp2p -->|"connects P2P"| node_remote
node_protocol -->|"creates attestations"| node_identity_keys
node_protocol -->|"encodes messages"| node_framing
node_session -->|"encrypts payloads"| node_noise
node_session -->|"frames messages"| node_framing
node_session -->|"creates attestations"| node_identity_keys
node_px1 -->|"uses node"| node_libp2p

click node_cli "https://github.com/alexrudloff/clawchat/blob/main/src/cli.ts"
click node_gateway_cli "https://github.com/alexrudloff/clawchat/blob/main/src/cli/gateway.ts"
click node_daemon "https://github.com/alexrudloff/clawchat/blob/main/src/daemon/server.ts"
click node_router "https://github.com/alexrudloff/clawchat/blob/main/src/daemon/message-router.ts"
click node_identity_manager "https://github.com/alexrudloff/clawchat/blob/main/src/daemon/identity-manager.ts"
click node_config "https://github.com/alexrudloff/clawchat/blob/main/src/daemon/gateway-config.ts"
click node_identity_keys "https://github.com/alexrudloff/clawchat/blob/main/src/identity/keys.ts"
click node_wallet "https://github.com/alexrudloff/clawchat/blob/main/src/identity/wallet.ts"
click node_policy "https://github.com/alexrudloff/clawchat/blob/main/src/types/gateway.ts"
click node_libp2p "https://github.com/alexrudloff/clawchat/blob/main/src/net/libp2p-node.ts"
click node_protocol "https://github.com/alexrudloff/clawchat/blob/main/src/net/snap2p-protocol.ts"
click node_session "https://github.com/alexrudloff/clawchat/blob/main/src/net/session.ts"
click node_noise "https://github.com/alexrudloff/clawchat/blob/main/src/crypto/noise.ts"
click node_framing "https://github.com/alexrudloff/clawchat/blob/main/src/wire/framing.ts"
click node_px1 "https://github.com/alexrudloff/clawchat/blob/main/src/net/px1.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_cli,node_gateway_cli toneBlue
class node_daemon,node_router toneAmber
class node_identity_manager,node_config,node_identity_keys,node_wallet,node_policy toneMint
class node_libp2p,node_protocol,node_session,node_noise,node_framing,node_px1 toneRose
class node_agent,node_remote toneIndigo
```

## Components

### Local Client

- [CLI Commands](https://github.com/alexrudloff/clawchat/blob/main/src/cli.ts): `src/cli.ts`
- [Gateway Setup](https://github.com/alexrudloff/clawchat/blob/main/src/cli/gateway.ts): `src/cli/gateway.ts`

### Gateway Runtime

- [Gateway Daemon](https://github.com/alexrudloff/clawchat/blob/main/src/daemon/server.ts): `src/daemon/server.ts`
- [Message Routing](https://github.com/alexrudloff/clawchat/blob/main/src/daemon/message-router.ts): `src/daemon/message-router.ts`

### Identity and Policy

- [Identity Runtime](https://github.com/alexrudloff/clawchat/blob/main/src/daemon/identity-manager.ts): `src/daemon/identity-manager.ts`
- [Gateway Configuration](https://github.com/alexrudloff/clawchat/blob/main/src/daemon/gateway-config.ts): `src/daemon/gateway-config.ts`
- [Identity and Attestation](https://github.com/alexrudloff/clawchat/blob/main/src/identity/keys.ts): `src/identity/keys.ts`
- [Stacks Wallet](https://github.com/alexrudloff/clawchat/blob/main/src/identity/wallet.ts): `src/identity/wallet.ts`
- [Identity ACL and Wake](https://github.com/alexrudloff/clawchat/blob/main/src/types/gateway.ts): `src/types/gateway.ts`

### P2P Transport

- [Libp2p Node](https://github.com/alexrudloff/clawchat/blob/main/src/net/libp2p-node.ts): `src/net/libp2p-node.ts`
- [SNaP2P Authentication](https://github.com/alexrudloff/clawchat/blob/main/src/net/snap2p-protocol.ts): `src/net/snap2p-protocol.ts`
- [Encrypted Session](https://github.com/alexrudloff/clawchat/blob/main/src/net/session.ts): `src/net/session.ts`
- [Noise Encryption](https://github.com/alexrudloff/clawchat/blob/main/src/crypto/noise.ts): `src/crypto/noise.ts`
- [Wire Framing](https://github.com/alexrudloff/clawchat/blob/main/src/wire/framing.ts): `src/wire/framing.ts`
- [PX-1 Peer Exchange](https://github.com/alexrudloff/clawchat/blob/main/src/net/px1.ts): `src/net/px1.ts`

### Other components

- **Agent**
- **Remote Gateway**

## Connections

- Agent → CLI Commands: invokes (evidence: `README.md`)
- CLI Commands → Gateway Daemon: uses IPC (evidence: `README.md`)
- Gateway Setup → Gateway Configuration: configures (evidence: `src/cli/gateway.ts`)
- CLI Commands → Gateway Daemon: calls commands (evidence: `src/cli.ts`)
- Gateway Daemon → Gateway Configuration: loads (evidence: `src/daemon/server.ts`)
- Gateway Daemon → Identity Runtime: manages identities (evidence: `src/daemon/server.ts`)
- Gateway Daemon → Message Routing: routes messages (evidence: `src/daemon/server.ts`)
- Identity Runtime → Identity and Attestation: loads identity (evidence: `src/daemon/identity-manager.ts`)
- Identity and Attestation → Stacks Wallet: derives wallet (evidence: `src/identity/keys.ts`)
- Gateway Configuration → Identity ACL and Wake: defines settings (evidence: `src/types/gateway.ts`)
- Gateway Daemon → Libp2p Node: starts node (evidence: `src/daemon/server.ts`)
- Gateway Daemon → SNaP2P Authentication: starts handler (evidence: `src/daemon/server.ts`)
- Gateway Daemon → PX-1 Peer Exchange: exchanges peers (evidence: `src/daemon/server.ts`)
- Libp2p Node → Remote Gateway: connects P2P (evidence: `README.md`)
- SNaP2P Authentication → Identity and Attestation: creates attestations (evidence: `src/net/snap2p-protocol.ts`)
- SNaP2P Authentication → Wire Framing: encodes messages (evidence: `src/net/snap2p-protocol.ts`)
- Encrypted Session → Noise Encryption: encrypts payloads (evidence: `src/net/session.ts`)
- Encrypted Session → Wire Framing: frames messages (evidence: `src/net/session.ts`)
- Encrypted Session → Identity and Attestation: creates attestations (evidence: `src/net/session.ts`)
- PX-1 Peer Exchange → Libp2p Node: uses node (evidence: `src/net/px1.ts`)
