# hllstr/sora-rs architecture

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

- Interactive diagram: https://gitdiagram.com/hllstr/sora-rs
- Repository: https://github.com/hllstr/sora-rs

## Overview

Sora-on-rust is a WhatsApp bot: it loads configuration and runtime state, connects through the WhatsApp client, processes inbound events, and dispatches commands or message behavior. Its command families cover general information, media downloads, group administration, owner controls, and utility tools; macros support sending text and media. The README confirms the bot’s identity and setup but gives few behavioral details. Some command-family links are shown as unverified because the sampled excerpts do not show how distributed command registration connects those modules to dispatch.

Main entry points: [`src/commands/cmd.rs`](https://github.com/hllstr/sora-rs/blob/main/src/commands/cmd.rs) (Command dispatch), [`src/handler.rs`](https://github.com/hllstr/sora-rs/blob/main/src/handler.rs) (Event handler), [`src/state.rs`](https://github.com/hllstr/sora-rs/blob/main/src/state.rs) (Runtime state), [`src/logger.rs`](https://github.com/hllstr/sora-rs/blob/main/src/logger.rs) (Logging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Startup<br/>[main.rs]"]
  node_config["Configuration<br/>[config.rs]"]
  node_state["Runtime state<br/>[state.rs]"]
  node_client["WhatsApp client<br/>[client.rs]"]
  node_handler["Event handler<br/>[handler.rs]"]
  node_logger["Logging<br/>[logger.rs]"]
end

subgraph group_commands["Commands"]
  node_dispatch["Command dispatch<br/>[cmd.rs]"]
  node_general["General commands"]
  node_play["Media playback<br/>[play.rs]"]
  node_reels["Reel downloads<br/>[reels.rs]"]
  node_groupadmin["Group administration"]
  node_owner["Owner controls"]
  node_tools["Bot tools"]
end

subgraph group_messaging["Messaging"]
  node_utils["Message utilities<br/>[utils.rs]"]
  node_sendmsg["Text sending<br/>[send_msg.rs]"]
  node_sendaudio["Audio sending<br/>[send_audio.rs]"]
  node_sendvideo["Video sending<br/>[send_video.rs]"]
end

node_operator(("Bot operator"))
node_whatsapp(("WhatsApp service"))

node_operator -->|"starts bot"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"loads state"| node_state
node_main -->|"creates client"| node_client
node_client -->|"uses settings"| node_config
node_client -->|"captures state"| node_state
node_client -->|"registers events"| node_handler
node_whatsapp -.->|"sends events"| node_handler
node_handler -->|"dispatches commands"| node_dispatch
node_handler -->|"reads and updates"| node_state
node_handler -->|"checks settings"| node_config
node_handler -->|"uses message helpers"| node_utils
node_handler -->|"logs errors"| node_logger
node_dispatch -->|"shares state"| node_state
node_dispatch -.->|"routes registered commands"| node_general
node_dispatch -.->|"routes registered commands"| node_play
node_dispatch -.->|"routes registered commands"| node_reels
node_dispatch -.->|"routes registered commands"| node_groupadmin
node_dispatch -.->|"routes registered commands"| node_owner
node_dispatch -.->|"routes registered commands"| node_tools
node_play -->|"logs activity"| node_logger
node_reels -->|"logs activity"| node_logger
node_owner -->|"updates settings"| node_state
node_owner -->|"uses configuration"| node_config
node_owner -->|"logs changes"| node_logger
node_tools -->|"uses helpers"| node_utils
node_tools -->|"logs activity"| node_logger
node_sendaudio -->|"loads media bytes"| node_utils
node_sendaudio -->|"reads expiry"| node_state
node_sendvideo -->|"loads media and thumbnail"| node_utils
node_sendvideo -->|"reads expiry"| node_state

click node_main "https://github.com/hllstr/sora-rs/blob/main/src/main.rs"
click node_config "https://github.com/hllstr/sora-rs/blob/main/src/config.rs"
click node_state "https://github.com/hllstr/sora-rs/blob/main/src/state.rs"
click node_client "https://github.com/hllstr/sora-rs/blob/main/src/client.rs"
click node_handler "https://github.com/hllstr/sora-rs/blob/main/src/handler.rs"
click node_logger "https://github.com/hllstr/sora-rs/blob/main/src/logger.rs"
click node_utils "https://github.com/hllstr/sora-rs/blob/main/src/utils.rs"
click node_dispatch "https://github.com/hllstr/sora-rs/blob/main/src/commands/cmd.rs"
click node_general "https://github.com/hllstr/sora-rs/tree/main/src/commands/general"
click node_play "https://github.com/hllstr/sora-rs/blob/main/src/commands/downloader/play.rs"
click node_reels "https://github.com/hllstr/sora-rs/blob/main/src/commands/downloader/reels.rs"
click node_groupadmin "https://github.com/hllstr/sora-rs/tree/main/src/commands/group"
click node_owner "https://github.com/hllstr/sora-rs/tree/main/src/commands/root"
click node_tools "https://github.com/hllstr/sora-rs/tree/main/src/commands/tools"
click node_sendmsg "https://github.com/hllstr/sora-rs/blob/main/src/macros/send_msg.rs"
click node_sendaudio "https://github.com/hllstr/sora-rs/blob/main/src/macros/send_audio.rs"
click node_sendvideo "https://github.com/hllstr/sora-rs/blob/main/src/macros/send_video.rs"

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_main,node_config,node_state,node_client,node_handler,node_logger toneBlue
class node_dispatch,node_general,node_play,node_reels,node_groupadmin,node_owner,node_tools toneAmber
class node_utils,node_sendmsg,node_sendaudio,node_sendvideo toneMint
class node_operator,node_whatsapp toneIndigo
```

## Components

### Runtime

- [Startup](https://github.com/hllstr/sora-rs/blob/main/src/main.rs): `src/main.rs`
- [Configuration](https://github.com/hllstr/sora-rs/blob/main/src/config.rs): `src/config.rs`
- [Runtime state](https://github.com/hllstr/sora-rs/blob/main/src/state.rs): `src/state.rs`
- [WhatsApp client](https://github.com/hllstr/sora-rs/blob/main/src/client.rs): `src/client.rs`
- [Event handler](https://github.com/hllstr/sora-rs/blob/main/src/handler.rs): `src/handler.rs`
- [Logging](https://github.com/hllstr/sora-rs/blob/main/src/logger.rs): `src/logger.rs`

### Commands

- [Command dispatch](https://github.com/hllstr/sora-rs/blob/main/src/commands/cmd.rs): `src/commands/cmd.rs`
- [General commands](https://github.com/hllstr/sora-rs/tree/main/src/commands/general): `src/commands/general`
- [Media playback](https://github.com/hllstr/sora-rs/blob/main/src/commands/downloader/play.rs): `src/commands/downloader/play.rs`
- [Reel downloads](https://github.com/hllstr/sora-rs/blob/main/src/commands/downloader/reels.rs): `src/commands/downloader/reels.rs`
- [Group administration](https://github.com/hllstr/sora-rs/tree/main/src/commands/group): `src/commands/group`
- [Owner controls](https://github.com/hllstr/sora-rs/tree/main/src/commands/root): `src/commands/root`
- [Bot tools](https://github.com/hllstr/sora-rs/tree/main/src/commands/tools): `src/commands/tools`

### Messaging

- [Message utilities](https://github.com/hllstr/sora-rs/blob/main/src/utils.rs): `src/utils.rs`
- [Text sending](https://github.com/hllstr/sora-rs/blob/main/src/macros/send_msg.rs): `src/macros/send_msg.rs`
- [Audio sending](https://github.com/hllstr/sora-rs/blob/main/src/macros/send_audio.rs): `src/macros/send_audio.rs`
- [Video sending](https://github.com/hllstr/sora-rs/blob/main/src/macros/send_video.rs): `src/macros/send_video.rs`

### Other components

- **Bot operator**
- **WhatsApp service**

## Connections

- Bot operator → Startup: starts bot (evidence: `README.md`)
- Startup → Configuration: loads settings (evidence: `src/main.rs`)
- Startup → Runtime state: loads state (evidence: `src/main.rs`)
- Startup → WhatsApp client: creates client (evidence: `src/main.rs`)
- WhatsApp client → Configuration: uses settings (evidence: `src/client.rs`)
- WhatsApp client → Runtime state: captures state (evidence: `src/client.rs`)
- WhatsApp client → Event handler: registers events (evidence: `src/client.rs`)
- WhatsApp service → Event handler: sends events
- Event handler → Command dispatch: dispatches commands (evidence: `src/handler.rs`)
- Event handler → Runtime state: reads and updates (evidence: `src/handler.rs`)
- Event handler → Configuration: checks settings (evidence: `src/handler.rs`)
- Event handler → Message utilities: uses message helpers (evidence: `src/handler.rs`)
- Event handler → Logging: logs errors (evidence: `src/handler.rs`)
- Command dispatch → Runtime state: shares state (evidence: `src/commands/cmd.rs`)
- Command dispatch → General commands: routes registered commands (evidence: `src/commands/general/info.rs`)
- Command dispatch → Media playback: routes registered commands (evidence: `src/commands/downloader/play.rs`)
- Command dispatch → Reel downloads: routes registered commands
- Command dispatch → Group administration: routes registered commands
- Command dispatch → Owner controls: routes registered commands (evidence: `src/commands/root/spamedit.rs`)
- Command dispatch → Bot tools: routes registered commands (evidence: `src/commands/tools/translate.rs`)
- Media playback → Logging: logs activity (evidence: `src/commands/downloader/play.rs`)
- Reel downloads → Logging: logs activity (evidence: `src/commands/downloader/reels.rs`)
- Owner controls → Runtime state: updates settings (evidence: `src/commands/root/set.rs`)
- Owner controls → Configuration: uses configuration (evidence: `src/commands/root/set.rs`)
- Owner controls → Logging: logs changes (evidence: `src/commands/root/set.rs`)
- Bot tools → Message utilities: uses helpers (evidence: `src/commands/tools/translate.rs`)
- Bot tools → Logging: logs activity (evidence: `src/commands/tools/translate.rs`)
- Audio sending → Message utilities: loads media bytes (evidence: `src/macros/send_audio.rs`)
- Audio sending → Runtime state: reads expiry (evidence: `src/macros/send_audio.rs`)
- Video sending → Message utilities: loads media and thumbnail (evidence: `src/macros/send_video.rs`)
- Video sending → Runtime state: reads expiry (evidence: `src/macros/send_video.rs`)
