# hotaruproject/hotaru architecture

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

## Overview

Hotaru is a Telegram automation runtime for managing accounts and loading modular commands and handlers. The principal workflow is account setup and configuration, module activation and registration, then runtime dispatch of Telegram events to commands or module code and delivery of responses. The relay package supplies guarded Telegram/network access and sandbox capabilities. The README contains no architecture details; edges below rely on the supplied source excerpts and SOURCE INDEX references, which show imports but not all runtime wiring.

Main entry points: [`hotaru/runtime.py`](https://github.com/hotaruproject/hotaru/blob/main/hotaru/runtime.py) (Runtime), [`hotaru/activation.py`](https://github.com/hotaruproject/hotaru/blob/main/hotaru/activation.py) (Module Activation), [`hotaru/response.py`](https://github.com/hotaruproject/hotaru/blob/main/hotaru/response.py) (Response Service), [`hotaru/kernel.py`](https://github.com/hotaruproject/hotaru/blob/main/hotaru/kernel.py) (Command Kernel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Accounts &amp; Configuration"]
  node_accounts["Account Manager<br/>[accounts.py]"]
  node_login["Account Login<br/>[login.py]"]
  node_config["Runtime Config<br/>[config.py]"]
  node_state[("Persistent State<br/>[state.py]")]
end

subgraph group_runtime["Dispatch &amp; Modules"]
  node_runtime["Runtime<br/>[runtime.py]"]
  node_activation["Module Activation<br/>[activation.py]"]
  node_modules["Module Loader<br/>[modules.py]"]
  node_kernel["Command Kernel<br/>[kernel.py]"]
  node_registry["Command Registry<br/>[registry.py]"]
  node_commands["Command Parsing<br/>[commands.py]"]
  node_tasks["Task Supervisor<br/>[tasks.py]"]
  node_backup["Module Backup<br/>[backup.py]"]
end

subgraph group_security["Isolation &amp; Capabilities"]
  node_sandbox["Module Sandbox<br/>[sandbox.py]"]
  node_capabilities["Capability Host<br/>[caps.py]"]
  node_firewall["Access Firewall<br/>[firewall.py]"]
end

subgraph group_telegram["Telegram Interaction"]
  node_response["Response Service<br/>[response.py]"]
  node_callbacks["Callback Handling<br/>[callbacks.py]"]
  node_proxies["Telegram Proxies<br/>[proxies.py]"]
  node_files["File Helpers<br/>[files.py]"]
  node_emoji["Emoji Formatting<br/>[emoji.py]"]
  node_rpc["Telegram RPC<br/>[rpc.py]"]
end

node_user(("Operator"))
node_telegram_api["Telegram API"]

node_user -->|"manages accounts"| node_accounts
node_accounts -->|"persists account data"| node_state
node_accounts -->|"builds account config"| node_config
node_login -->|"uses account manager"| node_accounts
node_runtime -->|"handles login choices"| node_login
node_runtime -->|"uses configuration"| node_config
node_runtime -->|"dispatches module work"| node_modules
node_runtime -->|"dispatches commands"| node_kernel
node_runtime -->|"handles callbacks"| node_callbacks
node_runtime -->|"restores backups"| node_backup
node_runtime -->|"uses sandbox"| node_sandbox
node_activation -->|"activates modules"| node_modules
node_activation -->|"schedules module tasks"| node_tasks
node_activation -->|"registers commands"| node_registry
node_activation -->|"applies isolation"| node_firewall
node_modules -->|"registers commands"| node_registry
node_kernel -->|"resolves commands"| node_registry
node_kernel -->|"parses commands"| node_commands
node_kernel -->|"enforces isolation"| node_firewall
node_sandbox -->|"requests capabilities"| node_capabilities
node_capabilities -.->|"checks guarded access"| node_firewall
node_capabilities -->|"controls module lifecycle"| node_modules
node_response -->|"sends media"| node_files
node_response -->|"formats rich text"| node_emoji
node_response -->|"uses Telegram helpers"| node_proxies
node_callbacks -->|"enters trusted scope"| node_firewall
node_proxies -->|"makes RPC calls"| node_rpc
node_proxies -->|"uses file helpers"| node_files
node_response -.->|"delivers responses"| node_telegram_api
node_proxies -.->|"calls Telegram"| node_telegram_api

click node_accounts "https://github.com/hotaruproject/hotaru/blob/main/hotaru/accounts.py"
click node_login "https://github.com/hotaruproject/hotaru/blob/main/hotaru/login.py"
click node_config "https://github.com/hotaruproject/hotaru/blob/main/hotaru/config.py"
click node_state "https://github.com/hotaruproject/hotaru/blob/main/hotaru/state.py"
click node_runtime "https://github.com/hotaruproject/hotaru/blob/main/hotaru/runtime.py"
click node_activation "https://github.com/hotaruproject/hotaru/blob/main/hotaru/activation.py"
click node_modules "https://github.com/hotaruproject/hotaru/blob/main/hotaru/modules.py"
click node_kernel "https://github.com/hotaruproject/hotaru/blob/main/hotaru/kernel.py"
click node_registry "https://github.com/hotaruproject/hotaru/blob/main/hotaru/registry.py"
click node_commands "https://github.com/hotaruproject/hotaru/blob/main/hotaru/commands.py"
click node_tasks "https://github.com/hotaruproject/hotaru/blob/main/hotaru/tasks.py"
click node_backup "https://github.com/hotaruproject/hotaru/blob/main/hotaru/backup.py"
click node_sandbox "https://github.com/hotaruproject/hotaru/blob/main/relay/sandbox.py"
click node_capabilities "https://github.com/hotaruproject/hotaru/blob/main/relay/caps.py"
click node_firewall "https://github.com/hotaruproject/hotaru/blob/main/relay/firewall.py"
click node_response "https://github.com/hotaruproject/hotaru/blob/main/hotaru/response.py"
click node_callbacks "https://github.com/hotaruproject/hotaru/blob/main/hotaru/callbacks.py"
click node_proxies "https://github.com/hotaruproject/hotaru/blob/main/relay/proxies.py"
click node_files "https://github.com/hotaruproject/hotaru/blob/main/relay/files.py"
click node_emoji "https://github.com/hotaruproject/hotaru/blob/main/relay/emoji.py"
click node_rpc "https://github.com/hotaruproject/hotaru/blob/main/relay/rpc.py"

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_accounts,node_login,node_config,node_state toneBlue
class node_runtime,node_activation,node_modules,node_kernel,node_registry,node_commands,node_tasks,node_backup toneAmber
class node_sandbox,node_capabilities,node_firewall,node_telegram_api toneMint
class node_response,node_callbacks,node_proxies,node_files,node_emoji,node_rpc toneRose
class node_user toneIndigo
```

## Components

### Accounts & Configuration

- [Account Manager](https://github.com/hotaruproject/hotaru/blob/main/hotaru/accounts.py): `hotaru/accounts.py`
- [Account Login](https://github.com/hotaruproject/hotaru/blob/main/hotaru/login.py): `hotaru/login.py`
- [Runtime Config](https://github.com/hotaruproject/hotaru/blob/main/hotaru/config.py): `hotaru/config.py`
- [Persistent State](https://github.com/hotaruproject/hotaru/blob/main/hotaru/state.py): `hotaru/state.py`

### Dispatch & Modules

- [Runtime](https://github.com/hotaruproject/hotaru/blob/main/hotaru/runtime.py): `hotaru/runtime.py`
- [Module Activation](https://github.com/hotaruproject/hotaru/blob/main/hotaru/activation.py): `hotaru/activation.py`
- [Module Loader](https://github.com/hotaruproject/hotaru/blob/main/hotaru/modules.py): `hotaru/modules.py`
- [Command Kernel](https://github.com/hotaruproject/hotaru/blob/main/hotaru/kernel.py): `hotaru/kernel.py`
- [Command Registry](https://github.com/hotaruproject/hotaru/blob/main/hotaru/registry.py): `hotaru/registry.py`
- [Command Parsing](https://github.com/hotaruproject/hotaru/blob/main/hotaru/commands.py): `hotaru/commands.py`
- [Task Supervisor](https://github.com/hotaruproject/hotaru/blob/main/hotaru/tasks.py): `hotaru/tasks.py`
- [Module Backup](https://github.com/hotaruproject/hotaru/blob/main/hotaru/backup.py): `hotaru/backup.py`

### Isolation & Capabilities

- [Module Sandbox](https://github.com/hotaruproject/hotaru/blob/main/relay/sandbox.py): `relay/sandbox.py`
- [Capability Host](https://github.com/hotaruproject/hotaru/blob/main/relay/caps.py): `relay/caps.py`
- [Access Firewall](https://github.com/hotaruproject/hotaru/blob/main/relay/firewall.py): `relay/firewall.py`

### Telegram Interaction

- [Response Service](https://github.com/hotaruproject/hotaru/blob/main/hotaru/response.py): `hotaru/response.py`
- [Callback Handling](https://github.com/hotaruproject/hotaru/blob/main/hotaru/callbacks.py): `hotaru/callbacks.py`
- [Telegram Proxies](https://github.com/hotaruproject/hotaru/blob/main/relay/proxies.py): `relay/proxies.py`
- [File Helpers](https://github.com/hotaruproject/hotaru/blob/main/relay/files.py): `relay/files.py`
- [Emoji Formatting](https://github.com/hotaruproject/hotaru/blob/main/relay/emoji.py): `relay/emoji.py`
- [Telegram RPC](https://github.com/hotaruproject/hotaru/blob/main/relay/rpc.py): `relay/rpc.py`

### Other components

- **Operator**
- **Telegram API**

## Connections

- Operator → Account Manager: manages accounts
- Account Manager → Persistent State: persists account data (evidence: `hotaru/accounts.py`)
- Account Manager → Runtime Config: builds account config (evidence: `hotaru/accounts.py`)
- Account Login → Account Manager: uses account manager (evidence: `hotaru/login.py`)
- Runtime → Account Login: handles login choices (evidence: `hotaru/runtime.py`)
- Runtime → Runtime Config: uses configuration (evidence: `hotaru/runtime.py`)
- Runtime → Module Loader: dispatches module work (evidence: `hotaru/runtime.py`)
- Runtime → Command Kernel: dispatches commands (evidence: `hotaru/runtime.py`)
- Runtime → Callback Handling: handles callbacks (evidence: `hotaru/runtime.py`)
- Runtime → Module Backup: restores backups (evidence: `hotaru/runtime.py`)
- Runtime → Module Sandbox: uses sandbox (evidence: `hotaru/runtime.py`)
- Module Activation → Module Loader: activates modules (evidence: `hotaru/activation.py`)
- Module Activation → Task Supervisor: schedules module tasks (evidence: `hotaru/activation.py`)
- Module Activation → Command Registry: registers commands (evidence: `hotaru/activation.py`)
- Module Activation → Access Firewall: applies isolation (evidence: `hotaru/activation.py`)
- Module Loader → Command Registry: registers commands (evidence: `hotaru/modules.py`)
- Command Kernel → Command Registry: resolves commands (evidence: `hotaru/kernel.py`)
- Command Kernel → Command Parsing: parses commands (evidence: `hotaru/kernel.py`)
- Command Kernel → Access Firewall: enforces isolation (evidence: `hotaru/kernel.py`)
- Module Sandbox → Capability Host: requests capabilities (evidence: `relay/sandbox.py`)
- Capability Host → Access Firewall: checks guarded access (evidence: `relay/caps.py`)
- Capability Host → Module Loader: controls module lifecycle (evidence: `relay/caps.py`)
- Response Service → File Helpers: sends media (evidence: `hotaru/response.py`)
- Response Service → Emoji Formatting: formats rich text (evidence: `hotaru/response.py`)
- Response Service → Telegram Proxies: uses Telegram helpers (evidence: `hotaru/response.py`)
- Callback Handling → Access Firewall: enters trusted scope (evidence: `hotaru/callbacks.py`)
- Telegram Proxies → Telegram RPC: makes RPC calls (evidence: `relay/proxies.py`)
- Telegram Proxies → File Helpers: uses file helpers (evidence: `relay/proxies.py`)
- Response Service → Telegram API: delivers responses
- Telegram Proxies → Telegram API: calls Telegram
