How hotaruproject/hotaru works
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: runtime.py Runtime · activation.py Module Activation · response.py Response Service · kernel.py Command Kernel
Components 23
Accounts & Configuration
- Account Manager
hotaru/accounts.py - Account Login
hotaru/login.py - Runtime Config
hotaru/config.py - Persistent State
hotaru/state.py
Dispatch & Modules
- Runtime
hotaru/runtime.py - Module Activation
hotaru/activation.py - Module Loader
hotaru/modules.py - Command Kernel
hotaru/kernel.py - Command Registry
hotaru/registry.py - Command Parsing
hotaru/commands.py - Task Supervisor
hotaru/tasks.py - Module Backup
hotaru/backup.py
Isolation & Capabilities
- Module Sandbox
relay/sandbox.py - Capability Host
relay/caps.py - Access Firewall
relay/firewall.py
Telegram Interaction
- Response Service
hotaru/response.py - Callback Handling
hotaru/callbacks.py - Telegram Proxies
relay/proxies.py - File Helpers
relay/files.py - Emoji Formatting
relay/emoji.py - Telegram RPC
relay/rpc.py
Other components
- Operator
- Telegram API
Connections 30
- Operator → Account Manager: manages accounts
- Account Manager → Persistent State: persists account data
hotaru/accounts.py - Account Manager → Runtime Config: builds account config
hotaru/accounts.py - Account Login → Account Manager: uses account manager
hotaru/login.py - Runtime → Account Login: handles login choices
hotaru/runtime.py - Runtime → Runtime Config: uses configuration
hotaru/runtime.py - Runtime → Module Loader: dispatches module work
hotaru/runtime.py - Runtime → Command Kernel: dispatches commands
hotaru/runtime.py - Runtime → Callback Handling: handles callbacks
hotaru/runtime.py - Runtime → Module Backup: restores backups
hotaru/runtime.py - Runtime → Module Sandbox: uses sandbox
hotaru/runtime.py - Module Activation → Module Loader: activates modules
hotaru/activation.py - Module Activation → Task Supervisor: schedules module tasks
hotaru/activation.py - Module Activation → Command Registry: registers commands
hotaru/activation.py - Module Activation → Access Firewall: applies isolation
hotaru/activation.py - Module Loader → Command Registry: registers commands
hotaru/modules.py - Command Kernel → Command Registry: resolves commands
hotaru/kernel.py - Command Kernel → Command Parsing: parses commands
hotaru/kernel.py - Command Kernel → Access Firewall: enforces isolation
hotaru/kernel.py - Module Sandbox → Capability Host: requests capabilities
relay/sandbox.py - Capability Host → Access Firewall: checks guarded access
relay/caps.py - Capability Host → Module Loader: controls module lifecycle
relay/caps.py - Response Service → File Helpers: sends media
hotaru/response.py - Response Service → Emoji Formatting: formats rich text
hotaru/response.py - Response Service → Telegram Proxies: uses Telegram helpers
hotaru/response.py - Callback Handling → Access Firewall: enters trusted scope
hotaru/callbacks.py - Telegram Proxies → Telegram RPC: makes RPC calls
relay/proxies.py - Telegram Proxies → File Helpers: uses file helpers
relay/proxies.py - Response Service → Telegram API: delivers responses
- Telegram Proxies → Telegram API: calls Telegram