# kyleparisi/ganclaw architecture

> Architecture diagram of the GitHub repository kyleparisi/ganclaw, 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/kyleparisi/ganclaw
- Repository: https://github.com/kyleparisi/ganclaw

## Overview

ganclaw is a self-hosted gateway from Telegram and local automation clients to coding-agent CLIs. Its main workflow accepts a chat or API request, routes an agent turn, runs it through the configured provider fallback chain, and returns or delivers the reply; chat sessions persist in SQLite. Separate branches cover Telegram media and voice transcription, MCP tools, health alerts, and OpenClaw compatibility. Edges cite README-level architecture or shown source references; some subsystem internals are unsampled, so their links are documented rather than inferred from names.

Main entry points: [`internal/router/router.go`](https://github.com/kyleparisi/ganclaw/blob/main/internal/router/router.go) (Conversation router), [`internal/api/server.go`](https://github.com/kyleparisi/ganclaw/blob/main/internal/api/server.go) (Local API), [`internal/telegram/bot.go`](https://github.com/kyleparisi/ganclaw/blob/main/internal/telegram/bot.go) (Telegram bot), [`cmd/ganclaw/client.go`](https://github.com/kyleparisi/ganclaw/blob/main/cmd/ganclaw/client.go) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_telegram_bot["Telegram bot<br/>[bot.go]"]
  node_cli["CLI commands<br/>[client.go]"]
  node_compat["OpenClaw compatibility<br/>[compat.go]"]
end

subgraph group_gateway["Gateway runtime"]
  node_api["Local API<br/>[server.go]"]
  node_gateway_core["Gateway dispatch<br/>[gateway.go]"]
  node_router["Conversation router<br/>[router.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_agents["Agent execution"]
  node_agent["Agent workspace<br/>[agent.go]"]
  node_provider_chain["Provider fallback<br/>[chain.go]"]
  node_codex["Codex provider<br/>[codex.go]"]
  node_claude["Claude provider<br/>[claude.go]"]
  node_mcp_tools["Agent MCP tools<br/>[agenttools.go]"]
end

subgraph group_channels["Chat and media"]
  node_telegram_media["Media transfer<br/>[files.go]"]
  node_attachments["Attachment storage<br/>[attachments.go]"]
  node_transcription["Voice transcription<br/>[transcribe.go]"]
end

subgraph group_operations["State and operations"]
  node_store[("SQLite state<br/>[store.go]")]
  node_monitor["Health monitor<br/>[monitor.go]"]
  node_health_cli["Health checks<br/>[check.go]"]
  node_updater["CLI updater<br/>[updater.go]"]
end

node_telegram_user(("Telegram user"))
node_automation(("Schedulers and scripts"))
node_mcp_servers["External MCP servers"]
node_telegram_service["Telegram service"]
node_audio_tools["ffmpeg and whisper.cpp"]
node_provider_clis["Agent CLI processes"]

node_telegram_user -->|"sends messages"| node_telegram_bot
node_telegram_bot -->|"submits turns"| node_router
node_automation -->|"invokes commands"| node_cli
node_cli -->|"calls over socket"| node_api
node_compat -->|"uses local API"| node_api
node_api -->|"dispatches requests"| node_gateway_core
node_gateway_core -->|"submits turns"| node_router
node_router -->|"loads workspace"| node_agent
node_router -->|"runs turn"| node_provider_chain
node_provider_chain -->|"tries provider"| node_codex
node_provider_chain -->|"falls back"| node_claude
node_codex -->|"drives app-server"| node_provider_clis
node_claude -->|"runs per turn"| node_provider_clis
node_provider_clis -.->|"accesses configured tools"| node_mcp_servers
node_router -->|"loads and saves sessions"| node_store
node_api -->|"claims idempotency keys"| node_store
node_telegram_bot -->|"polls and replies"| node_telegram_service
node_telegram_bot -->|"handles attachments"| node_telegram_media
node_telegram_media -->|"stores files"| node_attachments
node_router -.->|"transcribes voice notes"| node_transcription
node_transcription -->|"runs local tools"| node_audio_tools
node_router -.->|"offers agent tools"| node_mcp_tools
node_health_cli -->|"checks gateway"| node_api
node_health_cli -->|"evaluates alerts"| node_monitor
node_monitor -.->|"sends alerts"| node_telegram_service
node_config -.->|"configures runtime"| node_gateway_core
node_cli -->|"requests CLI updates"| node_updater
node_updater -.->|"updates binaries"| node_provider_clis

click node_telegram_bot "https://github.com/kyleparisi/ganclaw/blob/main/internal/telegram/bot.go"
click node_cli "https://github.com/kyleparisi/ganclaw/blob/main/cmd/ganclaw/client.go"
click node_compat "https://github.com/kyleparisi/ganclaw/blob/main/cmd/ganclaw/compat.go"
click node_api "https://github.com/kyleparisi/ganclaw/blob/main/internal/api/server.go"
click node_gateway_core "https://github.com/kyleparisi/ganclaw/blob/main/internal/gateway/gateway.go"
click node_router "https://github.com/kyleparisi/ganclaw/blob/main/internal/router/router.go"
click node_config "https://github.com/kyleparisi/ganclaw/blob/main/internal/config/config.go"
click node_agent "https://github.com/kyleparisi/ganclaw/blob/main/internal/agent/agent.go"
click node_provider_chain "https://github.com/kyleparisi/ganclaw/blob/main/internal/provider/chain.go"
click node_codex "https://github.com/kyleparisi/ganclaw/blob/main/internal/provider/codex/codex.go"
click node_claude "https://github.com/kyleparisi/ganclaw/blob/main/internal/provider/claude/claude.go"
click node_mcp_tools "https://github.com/kyleparisi/ganclaw/blob/main/internal/agenttools/agenttools.go"
click node_telegram_media "https://github.com/kyleparisi/ganclaw/blob/main/internal/telegram/files.go"
click node_attachments "https://github.com/kyleparisi/ganclaw/blob/main/internal/attachments/attachments.go"
click node_transcription "https://github.com/kyleparisi/ganclaw/blob/main/internal/transcribe/transcribe.go"
click node_store "https://github.com/kyleparisi/ganclaw/blob/main/internal/store/store.go"
click node_monitor "https://github.com/kyleparisi/ganclaw/blob/main/internal/monitor/monitor.go"
click node_health_cli "https://github.com/kyleparisi/ganclaw/blob/main/cmd/ganclaw/check.go"
click node_updater "https://github.com/kyleparisi/ganclaw/blob/main/internal/updater/updater.go"

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_telegram_bot,node_cli,node_compat,node_telegram_user toneBlue
class node_api,node_gateway_core,node_router,node_config toneAmber
class node_agent,node_provider_chain,node_codex,node_claude,node_mcp_tools,node_mcp_servers toneMint
class node_telegram_media,node_attachments,node_transcription,node_automation toneRose
class node_store,node_monitor,node_health_cli,node_updater,node_telegram_service,node_audio_tools,node_provider_clis toneIndigo
```

## Components

### Entry points

- [Telegram bot](https://github.com/kyleparisi/ganclaw/blob/main/internal/telegram/bot.go): `internal/telegram/bot.go`
- [CLI commands](https://github.com/kyleparisi/ganclaw/blob/main/cmd/ganclaw/client.go): `cmd/ganclaw/client.go`
- [OpenClaw compatibility](https://github.com/kyleparisi/ganclaw/blob/main/cmd/ganclaw/compat.go): `cmd/ganclaw/compat.go`

### Gateway runtime

- [Local API](https://github.com/kyleparisi/ganclaw/blob/main/internal/api/server.go): `internal/api/server.go`
- [Gateway dispatch](https://github.com/kyleparisi/ganclaw/blob/main/internal/gateway/gateway.go): `internal/gateway/gateway.go`
- [Conversation router](https://github.com/kyleparisi/ganclaw/blob/main/internal/router/router.go): `internal/router/router.go`
- [Configuration](https://github.com/kyleparisi/ganclaw/blob/main/internal/config/config.go): `internal/config/config.go`

### Agent execution

- [Agent workspace](https://github.com/kyleparisi/ganclaw/blob/main/internal/agent/agent.go): `internal/agent/agent.go`
- [Provider fallback](https://github.com/kyleparisi/ganclaw/blob/main/internal/provider/chain.go): `internal/provider/chain.go`
- [Codex provider](https://github.com/kyleparisi/ganclaw/blob/main/internal/provider/codex/codex.go): `internal/provider/codex/codex.go`
- [Claude provider](https://github.com/kyleparisi/ganclaw/blob/main/internal/provider/claude/claude.go): `internal/provider/claude/claude.go`
- [Agent MCP tools](https://github.com/kyleparisi/ganclaw/blob/main/internal/agenttools/agenttools.go): `internal/agenttools/agenttools.go`

### Chat and media

- [Media transfer](https://github.com/kyleparisi/ganclaw/blob/main/internal/telegram/files.go): `internal/telegram/files.go`
- [Attachment storage](https://github.com/kyleparisi/ganclaw/blob/main/internal/attachments/attachments.go): `internal/attachments/attachments.go`
- [Voice transcription](https://github.com/kyleparisi/ganclaw/blob/main/internal/transcribe/transcribe.go): `internal/transcribe/transcribe.go`

### State and operations

- [SQLite state](https://github.com/kyleparisi/ganclaw/blob/main/internal/store/store.go): `internal/store/store.go`
- [Health monitor](https://github.com/kyleparisi/ganclaw/blob/main/internal/monitor/monitor.go): `internal/monitor/monitor.go`
- [Health checks](https://github.com/kyleparisi/ganclaw/blob/main/cmd/ganclaw/check.go): `cmd/ganclaw/check.go`
- [CLI updater](https://github.com/kyleparisi/ganclaw/blob/main/internal/updater/updater.go): `internal/updater/updater.go`

### Other components

- **Telegram user**
- **Schedulers and scripts**
- **External MCP servers**
- **Telegram service**
- **ffmpeg and whisper.cpp**
- **Agent CLI processes**

## Connections

- Telegram user → Telegram bot: sends messages
- Telegram bot → Conversation router: submits turns
- Schedulers and scripts → CLI commands: invokes commands
- CLI commands → Local API: calls over socket
- OpenClaw compatibility → Local API: uses local API (evidence: `cmd/ganclaw/compat.go`)
- Local API → Gateway dispatch: dispatches requests (evidence: `internal/gateway/gateway.go`)
- Gateway dispatch → Conversation router: submits turns (evidence: `internal/gateway/gateway.go`)
- Conversation router → Agent workspace: loads workspace (evidence: `internal/router/router.go`)
- Conversation router → Provider fallback: runs turn
- Provider fallback → Codex provider: tries provider (evidence: `internal/provider/chain.go`)
- Provider fallback → Claude provider: falls back (evidence: `internal/provider/chain.go`)
- Codex provider → Agent CLI processes: drives app-server
- Claude provider → Agent CLI processes: runs per turn
- Agent CLI processes → External MCP servers: accesses configured tools
- Conversation router → SQLite state: loads and saves sessions (evidence: `internal/router/router.go`)
- Local API → SQLite state: claims idempotency keys (evidence: `internal/api/server.go`)
- Telegram bot → Telegram service: polls and replies
- Telegram bot → Media transfer: handles attachments
- Media transfer → Attachment storage: stores files (evidence: `internal/telegram/files.go`)
- Conversation router → Voice transcription: transcribes voice notes
- Voice transcription → ffmpeg and whisper.cpp: runs local tools (evidence: `internal/transcribe/transcribe.go`)
- Conversation router → Agent MCP tools: offers agent tools
- Health checks → Local API: checks gateway (evidence: `cmd/ganclaw/check.go`)
- Health checks → Health monitor: evaluates alerts (evidence: `cmd/ganclaw/check.go`)
- Health monitor → Telegram service: sends alerts
- Configuration → Gateway dispatch: configures runtime
- CLI commands → CLI updater: requests CLI updates
- CLI updater → Agent CLI processes: updates binaries
