# sasha33396/remnanode-setup-bot architecture

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

- Interactive diagram: https://gitdiagram.com/sasha33396/remnanode-setup-bot
- Repository: https://github.com/sasha33396/remnanode-setup-bot

## Overview

Remnanode Setup Bot is a Telegram-operated Remnawave node deployment and maintenance service. Operators use the bot to prepare and provision nodes, then manage node IPs, DNS, certificates, host moves, inventory, and deployment recovery. The orchestration layer coordinates UI requests with panel APIs, SSH operations, certificate management, and persistent workflow state. The README documents these major capabilities; source excerpts show selected implementations and executable wiring, so some subsystem links are documented rather than directly verified in sampled calls.

Main entry points: [`internal/orchestrator/service.go`](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/service.go) (Workflow orchestration), [`internal/telegram/controller.go`](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/telegram/controller.go) (Bot UI and wizard), [`internal/orchestrator/ip_change.go`](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/ip_change.go) (IP change workflows), [`internal/remnawave/client.go`](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/remnawave/client.go) (Remnawave client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator interface"]
  node_telegram["Bot UI and wizard<br/>[controller.go]"]
  node_inventory["Node inventory<br/>[node_inventory.go]"]
  node_monitor["Node monitor<br/>[node_monitor.go]"]
end

subgraph group_workflow["Deployment workflows"]
  node_orchestrator["Workflow orchestration<br/>[service.go]"]
  node_telegram_adapter["Telegram adapter<br/>[telegram.go]"]
  node_provisioner["Provisioning stages<br/>[stages.go]"]
  node_preflight["SSH preflight<br/>[preflight.go]"]
  node_dns_sync["Remna to DNS sync<br/>[dns_sync.go]"]
  node_host_move["Host migration<br/>[node_host_move.go]"]
  node_ip_workflows["IP change workflows<br/>[ip_change.go]"]
end

subgraph group_integrations["Node integrations"]
  node_remnawave["Remnawave client<br/>[client.go]"]
  node_dns["DNS balancer<br/>[client.go]"]
  node_cherry["Cherry IP setup<br/>[service.go]"]
  node_royal["Royal IP setup<br/>[service.go]"]
  node_ssh["SSH access<br/>[client.go]"]
  node_certificates["Certificate manager<br/>[manager.go]"]
  node_bot_api["Telegram Bot API"]
  node_panel_service["Remnawave panel"]
  node_dns_service["DNS service"]
  node_node_host["Managed VPS"]
end

subgraph group_state["Persistence and recovery"]
  node_postgres[("PostgreSQL repository<br/>[postgres.go]")]
  node_recovery["Deployment recovery<br/>[service.go]"]
  node_engine["Stage engine<br/>[engine.go]"]
end

subgraph group_runtime["Runtime services"]
  node_config["Configuration<br/>[config.go]"]
  node_main["Service executable<br/>[main.go]"]
  node_health["Health endpoint<br/>[server.go]"]
  node_metrics["Metrics registry<br/>[registry.go]"]
end

node_operator(("Telegram operator"))

node_operator -->|"operates"| node_telegram
node_telegram -->|"polls and replies"| node_bot_api
node_telegram -->|"invokes application"| node_telegram_adapter
node_telegram_adapter -->|"adapts requests"| node_orchestrator
node_orchestrator -->|"runs provisioning"| node_provisioner
node_provisioner -->|"executes stages"| node_engine
node_provisioner -->|"preflights VPS"| node_preflight
node_preflight -->|"checks access"| node_ssh
node_orchestrator -->|"manages nodes"| node_remnawave
node_orchestrator -->|"updates DNS"| node_dns
node_orchestrator -->|"checks readiness"| node_certificates
node_orchestrator -->|"persists workflow"| node_postgres
node_engine -->|"records steps"| node_postgres
node_orchestrator -->|"recovers deployments"| node_recovery
node_telegram -->|"opens node views"| node_inventory
node_monitor -->|"sends alerts"| node_telegram
node_telegram -->|"starts IP changes"| node_ip_workflows
node_ip_workflows -->|"updates node address"| node_remnawave
node_ip_workflows -->|"updates matching zones"| node_dns
node_ip_workflows -->|"configures Cherry IP"| node_cherry
node_ip_workflows -->|"configures Royal IP"| node_royal
node_cherry -->|"connects to server"| node_ssh
node_royal -->|"connects to server"| node_ssh
node_host_move -->|"updates host mapping"| node_remnawave
node_host_move -->|"obtains SNI certificate"| node_certificates
node_host_move -->|"activates server config"| node_ssh
node_dns_sync -->|"reads node address"| node_remnawave
node_dns_sync -->|"repairs zone"| node_dns
node_remnawave -->|"calls panel API"| node_panel_service
node_dns -->|"calls DNS API"| node_dns_service
node_ssh -->|"runs remote commands"| node_node_host
node_main -->|"loads settings"| node_config
node_main -->|"starts bot controller"| node_telegram
node_main -->|"starts endpoint"| node_health
node_health -->|"checks database"| node_postgres
node_main -->|"wires registry"| node_metrics

click node_telegram "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/telegram/controller.go"
click node_inventory "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/telegram/node_inventory.go"
click node_monitor "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/telegram/node_monitor.go"
click node_orchestrator "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/service.go"
click node_telegram_adapter "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/telegram.go"
click node_provisioner "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/provisioner/stages.go"
click node_preflight "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/provisioner/preflight.go"
click node_dns_sync "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/dns_sync.go"
click node_host_move "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/node_host_move.go"
click node_ip_workflows "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/ip_change.go"
click node_remnawave "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/remnawave/client.go"
click node_dns "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/dnsbalancer/client.go"
click node_cherry "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/cherryip/service.go"
click node_royal "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/royalip/service.go"
click node_ssh "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/ssh/client.go"
click node_certificates "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/certmanager/manager.go"
click node_postgres "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/repository/postgres/postgres.go"
click node_recovery "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/recovery/service.go"
click node_engine "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/provisioner/engine.go"
click node_config "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/config/config.go"
click node_main "https://github.com/sasha33396/remnanode-setup-bot/blob/main/cmd/deployer/main.go"
click node_health "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/health/server.go"
click node_metrics "https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/metrics/registry.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,node_inventory,node_monitor toneBlue
class node_orchestrator,node_telegram_adapter,node_provisioner,node_preflight,node_dns_sync,node_host_move,node_ip_workflows toneAmber
class node_remnawave,node_dns,node_cherry,node_royal,node_ssh,node_certificates,node_bot_api,node_panel_service,node_dns_service,node_node_host toneMint
class node_postgres,node_recovery,node_engine toneRose
class node_config,node_main,node_health,node_metrics,node_operator toneIndigo
```

## Components

### Operator interface

- [Bot UI and wizard](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/telegram/controller.go): `internal/telegram/controller.go`
- [Node inventory](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/telegram/node_inventory.go): `internal/telegram/node_inventory.go`
- [Node monitor](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/telegram/node_monitor.go): `internal/telegram/node_monitor.go`

### Deployment workflows

- [Workflow orchestration](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/service.go): `internal/orchestrator/service.go`
- [Telegram adapter](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/telegram.go): `internal/orchestrator/telegram.go`
- [Provisioning stages](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/provisioner/stages.go): `internal/provisioner/stages.go`
- [SSH preflight](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/provisioner/preflight.go): `internal/provisioner/preflight.go`
- [Remna to DNS sync](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/dns_sync.go): `internal/orchestrator/dns_sync.go`
- [Host migration](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/node_host_move.go): `internal/orchestrator/node_host_move.go`
- [IP change workflows](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/orchestrator/ip_change.go): `internal/orchestrator/ip_change.go`

### Node integrations

- [Remnawave client](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/remnawave/client.go): `internal/remnawave/client.go`
- [DNS balancer](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/dnsbalancer/client.go): `internal/dnsbalancer/client.go`
- [Cherry IP setup](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/cherryip/service.go): `internal/cherryip/service.go`
- [Royal IP setup](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/royalip/service.go): `internal/royalip/service.go`
- [SSH access](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/ssh/client.go): `internal/ssh/client.go`
- [Certificate manager](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/certmanager/manager.go): `internal/certmanager/manager.go`
- **Telegram Bot API**
- **Remnawave panel**
- **DNS service**
- **Managed VPS**

### Persistence and recovery

- [PostgreSQL repository](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/repository/postgres/postgres.go): `internal/repository/postgres/postgres.go`
- [Deployment recovery](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/recovery/service.go): `internal/recovery/service.go`
- [Stage engine](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/provisioner/engine.go): `internal/provisioner/engine.go`

### Runtime services

- [Configuration](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/config/config.go): `internal/config/config.go`
- [Service executable](https://github.com/sasha33396/remnanode-setup-bot/blob/main/cmd/deployer/main.go): `cmd/deployer/main.go`
- [Health endpoint](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/health/server.go): `internal/health/server.go`
- [Metrics registry](https://github.com/sasha33396/remnanode-setup-bot/blob/main/internal/metrics/registry.go): `internal/metrics/registry.go`

### Other components

- **Telegram operator**

## Connections

- Telegram operator → Bot UI and wizard: operates (evidence: `README.md`)
- Bot UI and wizard → Telegram Bot API: polls and replies (evidence: `README.md`)
- Bot UI and wizard → Telegram adapter: invokes application (evidence: `README.md`)
- Telegram adapter → Workflow orchestration: adapts requests (evidence: `README.md`)
- Workflow orchestration → Provisioning stages: runs provisioning (evidence: `README.md`)
- Provisioning stages → Stage engine: executes stages (evidence: `internal/provisioner/engine.go`)
- Provisioning stages → SSH preflight: preflights VPS (evidence: `README.md`)
- SSH preflight → SSH access: checks access (evidence: `README.md`)
- Workflow orchestration → Remnawave client: manages nodes (evidence: `internal/orchestrator/service.go`)
- Workflow orchestration → DNS balancer: updates DNS (evidence: `internal/orchestrator/service.go`)
- Workflow orchestration → Certificate manager: checks readiness (evidence: `internal/orchestrator/service.go`)
- Workflow orchestration → PostgreSQL repository: persists workflow (evidence: `README.md`)
- Stage engine → PostgreSQL repository: records steps (evidence: `internal/provisioner/engine.go`)
- Workflow orchestration → Deployment recovery: recovers deployments (evidence: `README.md`)
- Bot UI and wizard → Node inventory: opens node views (evidence: `README.md`)
- Node monitor → Bot UI and wizard: sends alerts (evidence: `README.md`)
- Bot UI and wizard → IP change workflows: starts IP changes (evidence: `README.md`)
- IP change workflows → Remnawave client: updates node address (evidence: `README.md`)
- IP change workflows → DNS balancer: updates matching zones (evidence: `README.md`)
- IP change workflows → Cherry IP setup: configures Cherry IP (evidence: `README.md`)
- IP change workflows → Royal IP setup: configures Royal IP (evidence: `README.md`)
- Cherry IP setup → SSH access: connects to server (evidence: `internal/cherryip/service.go`)
- Royal IP setup → SSH access: connects to server (evidence: `internal/royalip/service.go`)
- Host migration → Remnawave client: updates host mapping (evidence: `README.md`)
- Host migration → Certificate manager: obtains SNI certificate (evidence: `README.md`)
- Host migration → SSH access: activates server config (evidence: `README.md`)
- Remna to DNS sync → Remnawave client: reads node address (evidence: `README.md`)
- Remna to DNS sync → DNS balancer: repairs zone (evidence: `README.md`)
- Remnawave client → Remnawave panel: calls panel API (evidence: `internal/remnawave/client.go`)
- DNS balancer → DNS service: calls DNS API (evidence: `internal/dnsbalancer/client.go`)
- SSH access → Managed VPS: runs remote commands (evidence: `README.md`)
- Service executable → Configuration: loads settings (evidence: `cmd/deployer/main.go`)
- Service executable → Bot UI and wizard: starts bot controller (evidence: `cmd/deployer/main.go`)
- Service executable → Health endpoint: starts endpoint (evidence: `cmd/deployer/main.go`)
- Health endpoint → PostgreSQL repository: checks database
- Service executable → Metrics registry: wires registry (evidence: `cmd/deployer/main.go`)
