# ngmaloney/clawchat architecture

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

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

## Overview

ClawChat is an Electron desktop chat client for OpenClaw gateways and Claude Code channel servers. The main workflow is to load or enter backend credentials, optionally establish an SSH tunnel, connect over WebSocket, select a session, then send messages and attachments while rendering streamed replies. The graph includes the documented session, markdown, slash-command, reconnect, and credential-persistence capabilities. Some subsystem links are documented rather than visible in sampled implementation; those links use the README as evidence.

Main entry points: [`src/lib/gateway-client.ts`](https://github.com/ngmaloney/clawchat/blob/main/src/lib/gateway-client.ts) (WebSocket client), [`src/App.tsx`](https://github.com/ngmaloney/clawchat/blob/main/src/App.tsx) (App coordinator), [`src/components/Dashboard.tsx`](https://github.com/ngmaloney/clawchat/blob/main/src/components/Dashboard.tsx) (Chat dashboard), [`src/components/ConnectScreen.tsx`](https://github.com/ngmaloney/clawchat/blob/main/src/components/ConnectScreen.tsx) (Connect screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connection["Connection and backends"]
  node_app["App coordinator<br/>[App.tsx]"]
  node_connect["Connect screen<br/>[ConnectScreen.tsx]"]
  node_gatewayhook["Gateway lifecycle<br/>[useGateway.ts]"]
  node_wsclient["WebSocket client<br/>[gateway-client.ts]"]
  node_openclaw{{"OpenClaw gateway"}}
  node_channel{{"Claude channel server"}}
  node_ssh["SSH tunnel<br/>[main.ts]"]
  node_identity["Device identity signing"]
end

subgraph group_chat["Chat experience"]
  node_dashboard["Chat dashboard<br/>[Dashboard.tsx]"]
  node_chatview["Chat view<br/>[ChatView.tsx]"]
  node_chatstate["Chat state and streaming<br/>[useChat.ts]"]
  node_input["Message composer<br/>[MessageInput.tsx]"]
  node_slash["Slash commands"]
  node_fileutils["Attachment encoding<br/>[file-utils.ts]"]
  node_preview["Attachment preview"]
  node_bubble["Markdown message display<br/>[MessageBubble.tsx]"]
  node_attachmentview["Message attachments"]
end

subgraph group_sessions["Sessions and protocol"]
  node_sessionshook["Session management<br/>[useSessions.ts]"]
  node_sidebar["Session sidebar<br/>[Sidebar.tsx]"]
  node_status["Connection status<br/>[StatusBar.tsx]"]
  node_protocol["Gateway protocol types<br/>[protocol.ts]"]
end

subgraph group_desktop["Desktop integration"]
  node_electron["Desktop main process<br/>[main.ts]"]
  node_preload["Desktop API bridge<br/>[preload.ts]"]
  node_storage[("Local credential storage<br/>[main.ts]")]
end

node_user(("Desktop user"))

node_user -->|"configures connection"| node_connect
node_connect -->|"submits credentials"| node_app
node_app -->|"creates connection"| node_gatewayhook
node_gatewayhook -->|"manages lifecycle"| node_wsclient
node_wsclient -->|"connects WebSocket"| node_openclaw
node_wsclient -->|"connects WebSocket"| node_channel
node_connect -->|"starts tunnel"| node_ssh
node_app -->|"renders connected view"| node_dashboard
node_dashboard -->|"renders chat"| node_chatview
node_chatview -->|"uses chat state"| node_chatstate
node_chatview -.->|"renders composer"| node_input
node_chatview -->|"renders messages"| node_bubble
node_input -->|"shows commands"| node_slash
node_input -->|"renders previews"| node_preview
node_input -->|"encodes files"| node_fileutils
node_preview -->|"formats attachments"| node_fileutils
node_bubble -->|"renders attachments"| node_attachmentview
node_chatstate -->|"calls chat methods"| node_wsclient
node_chatstate -->|"uses message types"| node_protocol
node_wsclient -->|"signs handshake"| node_identity
node_dashboard -->|"manages sessions"| node_sessionshook
node_sessionshook -->|"lists sessions"| node_wsclient
node_sessionshook -->|"uses session types"| node_protocol
node_dashboard -.->|"renders navigation"| node_sidebar
node_dashboard -->|"renders status"| node_status
node_status -->|"uses connection types"| node_protocol
node_app -->|"loads and saves credentials"| node_storage
node_connect -->|"loads connection settings"| node_storage
node_preload -.->|"exposes store API"| node_storage
node_app -->|"uses desktop API"| node_preload
node_electron -.->|"provides renderer bridge"| node_preload

click node_app "https://github.com/ngmaloney/clawchat/blob/main/src/App.tsx"
click node_connect "https://github.com/ngmaloney/clawchat/blob/main/src/components/ConnectScreen.tsx"
click node_gatewayhook "https://github.com/ngmaloney/clawchat/blob/main/src/hooks/useGateway.ts"
click node_wsclient "https://github.com/ngmaloney/clawchat/blob/main/src/lib/gateway-client.ts"
click node_ssh "https://github.com/ngmaloney/clawchat/blob/main/electron/main.ts"
click node_dashboard "https://github.com/ngmaloney/clawchat/blob/main/src/components/Dashboard.tsx"
click node_chatview "https://github.com/ngmaloney/clawchat/blob/main/src/components/ChatView.tsx"
click node_chatstate "https://github.com/ngmaloney/clawchat/blob/main/src/hooks/useChat.ts"
click node_input "https://github.com/ngmaloney/clawchat/blob/main/src/components/MessageInput.tsx"
click node_slash "https://github.com/ngmaloney/clawchat/blob/main/src/components/SlashCommandMenu.tsx"
click node_fileutils "https://github.com/ngmaloney/clawchat/blob/main/src/lib/file-utils.ts"
click node_preview "https://github.com/ngmaloney/clawchat/blob/main/src/components/AttachmentPreview.tsx"
click node_bubble "https://github.com/ngmaloney/clawchat/blob/main/src/components/MessageBubble.tsx"
click node_attachmentview "https://github.com/ngmaloney/clawchat/blob/main/src/components/MessageAttachment.tsx"
click node_sessionshook "https://github.com/ngmaloney/clawchat/blob/main/src/hooks/useSessions.ts"
click node_sidebar "https://github.com/ngmaloney/clawchat/blob/main/src/components/Sidebar.tsx"
click node_status "https://github.com/ngmaloney/clawchat/blob/main/src/components/StatusBar.tsx"
click node_protocol "https://github.com/ngmaloney/clawchat/blob/main/src/types/protocol.ts"
click node_identity "https://github.com/ngmaloney/clawchat/blob/main/src/lib/device-crypto-ed25519.ts"
click node_electron "https://github.com/ngmaloney/clawchat/blob/main/electron/main.ts"
click node_preload "https://github.com/ngmaloney/clawchat/blob/main/electron/preload.ts"
click node_storage "https://github.com/ngmaloney/clawchat/blob/main/electron/main.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_app,node_connect,node_gatewayhook,node_wsclient,node_openclaw,node_channel,node_ssh,node_identity,node_user toneBlue
class node_dashboard,node_chatview,node_chatstate,node_input,node_slash,node_fileutils,node_preview,node_bubble,node_attachmentview toneAmber
class node_sessionshook,node_sidebar,node_status,node_protocol toneMint
class node_electron,node_preload,node_storage toneRose
```

## Components

### Connection and backends

- [App coordinator](https://github.com/ngmaloney/clawchat/blob/main/src/App.tsx): `src/App.tsx`
- [Connect screen](https://github.com/ngmaloney/clawchat/blob/main/src/components/ConnectScreen.tsx): `src/components/ConnectScreen.tsx`
- [Gateway lifecycle](https://github.com/ngmaloney/clawchat/blob/main/src/hooks/useGateway.ts): `src/hooks/useGateway.ts`
- [WebSocket client](https://github.com/ngmaloney/clawchat/blob/main/src/lib/gateway-client.ts): `src/lib/gateway-client.ts`
- **OpenClaw gateway**
- **Claude channel server**
- [SSH tunnel](https://github.com/ngmaloney/clawchat/blob/main/electron/main.ts): `electron/main.ts`
- [Device identity signing](https://github.com/ngmaloney/clawchat/blob/main/src/lib/device-crypto-ed25519.ts): `src/lib/device-crypto-ed25519.ts`

### Chat experience

- [Chat dashboard](https://github.com/ngmaloney/clawchat/blob/main/src/components/Dashboard.tsx): `src/components/Dashboard.tsx`
- [Chat view](https://github.com/ngmaloney/clawchat/blob/main/src/components/ChatView.tsx): `src/components/ChatView.tsx`
- [Chat state and streaming](https://github.com/ngmaloney/clawchat/blob/main/src/hooks/useChat.ts): `src/hooks/useChat.ts`
- [Message composer](https://github.com/ngmaloney/clawchat/blob/main/src/components/MessageInput.tsx): `src/components/MessageInput.tsx`
- [Slash commands](https://github.com/ngmaloney/clawchat/blob/main/src/components/SlashCommandMenu.tsx): `src/components/SlashCommandMenu.tsx`
- [Attachment encoding](https://github.com/ngmaloney/clawchat/blob/main/src/lib/file-utils.ts): `src/lib/file-utils.ts`
- [Attachment preview](https://github.com/ngmaloney/clawchat/blob/main/src/components/AttachmentPreview.tsx): `src/components/AttachmentPreview.tsx`
- [Markdown message display](https://github.com/ngmaloney/clawchat/blob/main/src/components/MessageBubble.tsx): `src/components/MessageBubble.tsx`
- [Message attachments](https://github.com/ngmaloney/clawchat/blob/main/src/components/MessageAttachment.tsx): `src/components/MessageAttachment.tsx`

### Sessions and protocol

- [Session management](https://github.com/ngmaloney/clawchat/blob/main/src/hooks/useSessions.ts): `src/hooks/useSessions.ts`
- [Session sidebar](https://github.com/ngmaloney/clawchat/blob/main/src/components/Sidebar.tsx): `src/components/Sidebar.tsx`
- [Connection status](https://github.com/ngmaloney/clawchat/blob/main/src/components/StatusBar.tsx): `src/components/StatusBar.tsx`
- [Gateway protocol types](https://github.com/ngmaloney/clawchat/blob/main/src/types/protocol.ts): `src/types/protocol.ts`

### Desktop integration

- [Desktop main process](https://github.com/ngmaloney/clawchat/blob/main/electron/main.ts): `electron/main.ts`
- [Desktop API bridge](https://github.com/ngmaloney/clawchat/blob/main/electron/preload.ts): `electron/preload.ts`
- [Local credential storage](https://github.com/ngmaloney/clawchat/blob/main/electron/main.ts): `electron/main.ts`

### Other components

- **Desktop user**

## Connections

- Desktop user → Connect screen: configures connection (evidence: `README.md`)
- Connect screen → App coordinator: submits credentials (evidence: `src/App.tsx`)
- App coordinator → Gateway lifecycle: creates connection (evidence: `src/App.tsx`)
- Gateway lifecycle → WebSocket client: manages lifecycle (evidence: `src/hooks/useGateway.ts`)
- WebSocket client → OpenClaw gateway: connects WebSocket (evidence: `README.md`)
- WebSocket client → Claude channel server: connects WebSocket (evidence: `README.md`)
- Connect screen → SSH tunnel: starts tunnel (evidence: `README.md`)
- App coordinator → Chat dashboard: renders connected view (evidence: `src/App.tsx`)
- Chat dashboard → Chat view: renders chat (evidence: `src/components/Dashboard.tsx`)
- Chat view → Chat state and streaming: uses chat state (evidence: `src/components/ChatView.tsx`)
- Chat view → Message composer: renders composer (evidence: `src/components/ChatView.tsx`)
- Chat view → Markdown message display: renders messages (evidence: `src/components/ChatView.tsx`)
- Message composer → Slash commands: shows commands (evidence: `src/components/MessageInput.tsx`)
- Message composer → Attachment preview: renders previews (evidence: `src/components/MessageInput.tsx`)
- Message composer → Attachment encoding: encodes files (evidence: `src/components/MessageInput.tsx`)
- Attachment preview → Attachment encoding: formats attachments (evidence: `src/components/AttachmentPreview.tsx`)
- Markdown message display → Message attachments: renders attachments (evidence: `src/components/MessageBubble.tsx`)
- Chat state and streaming → WebSocket client: calls chat methods (evidence: `src/hooks/useChat.ts`)
- Chat state and streaming → Gateway protocol types: uses message types (evidence: `src/hooks/useChat.ts`)
- WebSocket client → Device identity signing: signs handshake (evidence: `src/lib/gateway-client.ts`)
- Chat dashboard → Session management: manages sessions (evidence: `src/components/Dashboard.tsx`)
- Session management → WebSocket client: lists sessions (evidence: `src/hooks/useSessions.ts`)
- Session management → Gateway protocol types: uses session types (evidence: `src/hooks/useSessions.ts`)
- Chat dashboard → Session sidebar: renders navigation (evidence: `src/components/Dashboard.tsx`)
- Chat dashboard → Connection status: renders status (evidence: `src/components/Dashboard.tsx`)
- Connection status → Gateway protocol types: uses connection types (evidence: `src/components/StatusBar.tsx`)
- App coordinator → Local credential storage: loads and saves credentials (evidence: `src/App.tsx`)
- Connect screen → Local credential storage: loads connection settings (evidence: `src/components/ConnectScreen.tsx`)
- Desktop API bridge → Local credential storage: exposes store API (evidence: `electron/preload.ts`)
- App coordinator → Desktop API bridge: uses desktop API (evidence: `src/App.tsx`)
- Desktop main process → Desktop API bridge: provides renderer bridge
