# lifailon/openrouter-bot architecture

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

## Overview

OpenRouter Bot lets Telegram users chat with OpenRouter or compatible local models, with commands for model selection, history reset, and usage statistics. The main flow is Telegram updates → access and per-user state → streaming chat completion → Telegram response; OpenRouter generation usage is then recorded. Configuration, translations, vision input, model discovery, history, and persisted budgets are distinct supporting capabilities. Source excerpts show the main dispatch and chat flow; several README capabilities are documented but their command or configuration internals were not sampled, so those links are omitted where call ownership is unverified.

Main entry points: [`main.go`](https://github.com/lifailon/openrouter-bot/blob/main/main.go) (Update dispatcher), [`api/openrouter.go`](https://github.com/lifailon/openrouter-bot/blob/main/api/openrouter.go) (Streaming chat), [`user/usage_tracker.go`](https://github.com/lifailon/openrouter-bot/blob/main/user/usage_tracker.go) (Access and usage), [`user/users_manager.go`](https://github.com/lifailon/openrouter-bot/blob/main/user/users_manager.go) (User registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Bot entry"]
  node_main["Update dispatcher<br/>[main.go]"]
end

subgraph group_chat["Chat handling"]
  node_chat_handler["Streaming chat<br/>[openrouter.go]"]
  node_model_service["Model discovery<br/>[openrouter.go]"]
  node_vision["Vision input<br/>[openrouter.go]"]
end

subgraph group_state["User state"]
  node_user_manager["User registry<br/>[users_manager.go]"]
  node_usage_tracker["Access and usage<br/>[usage_tracker.go]"]
  node_usage_files[("Usage records")]
  node_history["Conversation history<br/>[history.go]"]
  node_user_types["User data types<br/>[types.go]"]
end

subgraph group_setup["Configuration"]
  node_config["Config loading<br/>[config.go]"]
  node_config_manager["Config watcher<br/>[config_manager.go]"]
  node_translations["Translations<br/>[lang.go]"]
end

node_telegram_user(("Telegram user"))
node_telegram["Telegram Bot API"]
node_llm["OpenAI-compatible API"]
node_openrouter_usage["Generation usage API"]

node_telegram_user -->|"sends updates"| node_telegram
node_telegram -->|"delivers updates"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"loads strings"| node_translations
node_main -->|"gets user"| node_user_manager
node_user_manager -->|"creates tracker"| node_usage_tracker
node_usage_tracker -->|"reads and writes"| node_usage_files
node_main -->|"checks access"| node_usage_tracker
node_main -->|"dispatches chat"| node_chat_handler
node_chat_handler -->|"reads and appends"| node_history
node_chat_handler -->|"builds image input"| node_vision
node_vision -->|"downloads image"| node_telegram
node_chat_handler -->|"streams completion"| node_llm
node_chat_handler -->|"sends streamed reply"| node_telegram
node_main -->|"requests free models"| node_model_service
node_model_service -->|"loads endpoint config"| node_config_manager
node_model_service -->|"fetches model list"| node_llm
node_main -->|"requests generation cost"| node_openrouter_usage
node_usage_tracker -->|"fetches generation"| node_openrouter_usage
node_main -->|"formats commands"| node_translations
node_config_manager -->|"reloads settings"| node_config

click node_main "https://github.com/lifailon/openrouter-bot/blob/main/main.go"
click node_config "https://github.com/lifailon/openrouter-bot/blob/main/config/config.go"
click node_config_manager "https://github.com/lifailon/openrouter-bot/blob/main/config/config_manager.go"
click node_translations "https://github.com/lifailon/openrouter-bot/blob/main/lang/lang.go"
click node_user_manager "https://github.com/lifailon/openrouter-bot/blob/main/user/users_manager.go"
click node_usage_tracker "https://github.com/lifailon/openrouter-bot/blob/main/user/usage_tracker.go"
click node_history "https://github.com/lifailon/openrouter-bot/blob/main/user/history.go"
click node_user_types "https://github.com/lifailon/openrouter-bot/blob/main/user/types.go"
click node_chat_handler "https://github.com/lifailon/openrouter-bot/blob/main/api/openrouter.go"
click node_model_service "https://github.com/lifailon/openrouter-bot/blob/main/api/openrouter.go"
click node_vision "https://github.com/lifailon/openrouter-bot/blob/main/api/openrouter.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_main,node_telegram_user toneBlue
class node_chat_handler,node_model_service,node_vision toneAmber
class node_user_manager,node_usage_tracker,node_usage_files,node_history,node_user_types,node_telegram,node_llm,node_openrouter_usage toneMint
class node_config,node_config_manager,node_translations toneRose
```

## Components

### Bot entry

- [Update dispatcher](https://github.com/lifailon/openrouter-bot/blob/main/main.go): `main.go`

### Chat handling

- [Streaming chat](https://github.com/lifailon/openrouter-bot/blob/main/api/openrouter.go): `api/openrouter.go`
- [Model discovery](https://github.com/lifailon/openrouter-bot/blob/main/api/openrouter.go): `api/openrouter.go`
- [Vision input](https://github.com/lifailon/openrouter-bot/blob/main/api/openrouter.go): `api/openrouter.go`

### User state

- [User registry](https://github.com/lifailon/openrouter-bot/blob/main/user/users_manager.go): `user/users_manager.go`
- [Access and usage](https://github.com/lifailon/openrouter-bot/blob/main/user/usage_tracker.go): `user/usage_tracker.go`
- **Usage records**
- [Conversation history](https://github.com/lifailon/openrouter-bot/blob/main/user/history.go): `user/history.go`
- [User data types](https://github.com/lifailon/openrouter-bot/blob/main/user/types.go): `user/types.go`

### Configuration

- [Config loading](https://github.com/lifailon/openrouter-bot/blob/main/config/config.go): `config/config.go`
- [Config watcher](https://github.com/lifailon/openrouter-bot/blob/main/config/config_manager.go): `config/config_manager.go`
- [Translations](https://github.com/lifailon/openrouter-bot/blob/main/lang/lang.go): `lang/lang.go`

### Other components

- **Telegram user**
- **Telegram Bot API**
- **OpenAI-compatible API**
- **Generation usage API**

## Connections

- Telegram user → Telegram Bot API: sends updates
- Telegram Bot API → Update dispatcher: delivers updates (evidence: `main.go`)
- Update dispatcher → Config loading: loads settings (evidence: `main.go`)
- Update dispatcher → Translations: loads strings (evidence: `main.go`)
- Update dispatcher → User registry: gets user (evidence: `main.go`)
- User registry → Access and usage: creates tracker (evidence: `user/users_manager.go`)
- Access and usage → Usage records: reads and writes (evidence: `user/usage_tracker.go`)
- Update dispatcher → Access and usage: checks access (evidence: `main.go`)
- Update dispatcher → Streaming chat: dispatches chat (evidence: `main.go`)
- Streaming chat → Conversation history: reads and appends (evidence: `api/openrouter.go`)
- Streaming chat → Vision input: builds image input (evidence: `api/openrouter.go`)
- Vision input → Telegram Bot API: downloads image (evidence: `api/openrouter.go`)
- Streaming chat → OpenAI-compatible API: streams completion (evidence: `api/openrouter.go`)
- Streaming chat → Telegram Bot API: sends streamed reply (evidence: `api/openrouter.go`)
- Update dispatcher → Model discovery: requests free models (evidence: `main.go`)
- Model discovery → Config watcher: loads endpoint config (evidence: `api/openrouter.go`)
- Model discovery → OpenAI-compatible API: fetches model list (evidence: `api/openrouter.go`)
- Update dispatcher → Generation usage API: requests generation cost (evidence: `main.go`)
- Access and usage → Generation usage API: fetches generation (evidence: `user/usage_tracker.go`)
- Update dispatcher → Translations: formats commands (evidence: `main.go`)
- Config watcher → Config loading: reloads settings (evidence: `config/config_manager.go`)
