# hongphong214365/agentstelegram architecture

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

- Interactive diagram: https://gitdiagram.com/hongphong214365/agentstelegram
- Repository: https://github.com/hongphong214365/agentstelegram

## Overview

agentsTelegram is an admin-controlled Telegram bot for running local Python files and returning their output or errors. The main workflow is Telegram command → registered handler → validated execution request → subprocess → Telegram reply. Separate commands provide help, ping, status, and recent logs. The README documents these capabilities; sampled source confirms their wiring and the execution/logging details shown below.

Main entry points: [`handlers/__init__.py`](https://github.com/hongphong214365/agentstelegram/blob/main/handlers/__init__.py) (Handler registration), [`handlers/run.py`](https://github.com/hongphong214365/agentstelegram/blob/main/handlers/run.py) (Run command), [`main.py`](https://github.com/hongphong214365/agentstelegram/blob/main/main.py) (Bot startup), [`log.py`](https://github.com/hongphong214365/agentstelegram/blob/main/log.py) (Logging and reads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_main["Bot startup<br/>[main.py]"]
  node_registry["Handler registration<br/>[__init__.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_commands["Command handlers"]
  node_start["Start command<br/>[start.py]"]
  node_ping["Ping command<br/>[ping.py]"]
  node_run_handler["Run command<br/>[run.py]"]
  node_status["Status command<br/>[status.py]"]
  node_log_handler["Log command<br/>[log.py]"]
end

subgraph group_execution["Execution and logs"]
  node_runner["Python runner<br/>[runner.py]"]
  node_log_module["Logging and reads<br/>[log.py]"]
  node_log_store[("Log file")]
end

node_admin(("Telegram admin"))
node_telegram{{"Telegram API"}}
node_script["Local Python file"]

node_main -->|"loads settings"| node_config
node_main -->|"registers handlers"| node_registry
node_main -->|"polls updates"| node_telegram
node_telegram -->|"delivers updates"| node_main
node_registry -->|"registers"| node_start
node_registry -->|"registers"| node_ping
node_registry -->|"registers"| node_run_handler
node_registry -->|"registers"| node_status
node_registry -->|"registers"| node_log_handler
node_admin -->|"sends commands"| node_telegram
node_start -->|"checks admin"| node_config
node_start -->|"replies with help"| node_telegram
node_ping -->|"replies online"| node_telegram
node_run_handler -->|"checks settings"| node_config
node_run_handler -->|"checks file"| node_script
node_run_handler -->|"runs file"| node_runner
node_runner -->|"executes"| node_script
node_runner -->|"logs errors"| node_log_module
node_run_handler -->|"replies with output"| node_telegram
node_status -->|"reads settings"| node_config
node_status -->|"replies with status"| node_telegram
node_log_handler -->|"gets recent logs"| node_log_module
node_log_module -->|"reads and writes"| node_log_store
node_log_handler -->|"replies with logs"| node_telegram
node_main -->|"logs startup"| node_log_module

click node_main "https://github.com/hongphong214365/agentstelegram/blob/main/main.py"
click node_registry "https://github.com/hongphong214365/agentstelegram/blob/main/handlers/__init__.py"
click node_config "https://github.com/hongphong214365/agentstelegram/blob/main/config.py"
click node_start "https://github.com/hongphong214365/agentstelegram/blob/main/handlers/start.py"
click node_ping "https://github.com/hongphong214365/agentstelegram/blob/main/handlers/ping.py"
click node_run_handler "https://github.com/hongphong214365/agentstelegram/blob/main/handlers/run.py"
click node_status "https://github.com/hongphong214365/agentstelegram/blob/main/handlers/status.py"
click node_log_handler "https://github.com/hongphong214365/agentstelegram/blob/main/handlers/log.py"
click node_runner "https://github.com/hongphong214365/agentstelegram/blob/main/runner.py"
click node_log_module "https://github.com/hongphong214365/agentstelegram/blob/main/log.py"
click node_log_store "https://github.com/hongphong214365/agentstelegram/tree/main/temp"

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_registry,node_config toneBlue
class node_start,node_ping,node_run_handler,node_status,node_log_handler toneAmber
class node_runner,node_log_module,node_log_store,node_telegram toneMint
class node_admin,node_script toneIndigo
```

## Components

### Bot runtime

- [Bot startup](https://github.com/hongphong214365/agentstelegram/blob/main/main.py): `main.py`
- [Handler registration](https://github.com/hongphong214365/agentstelegram/blob/main/handlers/__init__.py): `handlers/__init__.py`
- [Runtime config](https://github.com/hongphong214365/agentstelegram/blob/main/config.py): `config.py`

### Command handlers

- [Start command](https://github.com/hongphong214365/agentstelegram/blob/main/handlers/start.py): `handlers/start.py`
- [Ping command](https://github.com/hongphong214365/agentstelegram/blob/main/handlers/ping.py): `handlers/ping.py`
- [Run command](https://github.com/hongphong214365/agentstelegram/blob/main/handlers/run.py): `handlers/run.py`
- [Status command](https://github.com/hongphong214365/agentstelegram/blob/main/handlers/status.py): `handlers/status.py`
- [Log command](https://github.com/hongphong214365/agentstelegram/blob/main/handlers/log.py): `handlers/log.py`

### Execution and logs

- [Python runner](https://github.com/hongphong214365/agentstelegram/blob/main/runner.py): `runner.py`
- [Logging and reads](https://github.com/hongphong214365/agentstelegram/blob/main/log.py): `log.py`
- [Log file](https://github.com/hongphong214365/agentstelegram/tree/main/temp): `temp`

### Other components

- **Telegram admin**
- **Telegram API**
- **Local Python file**

## Connections

- Bot startup → Runtime config: loads settings
- Bot startup → Handler registration: registers handlers
- Bot startup → Telegram API: polls updates
- Telegram API → Bot startup: delivers updates
- Handler registration → Start command: registers
- Handler registration → Ping command: registers
- Handler registration → Run command: registers
- Handler registration → Status command: registers
- Handler registration → Log command: registers
- Telegram admin → Telegram API: sends commands
- Start command → Runtime config: checks admin
- Start command → Telegram API: replies with help
- Ping command → Telegram API: replies online
- Run command → Runtime config: checks settings
- Run command → Local Python file: checks file
- Run command → Python runner: runs file
- Python runner → Local Python file: executes
- Python runner → Logging and reads: logs errors
- Run command → Telegram API: replies with output
- Status command → Runtime config: reads settings
- Status command → Telegram API: replies with status
- Log command → Logging and reads: gets recent logs
- Logging and reads → Log file: reads and writes
- Log command → Telegram API: replies with logs
- Bot startup → Logging and reads: logs startup