# 20kevit/tele-mexc architecture

> Architecture diagram of the GitHub repository 20kevit/tele-mexc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/20kevit/tele-mexc
- Repository: https://github.com/20kevit/tele-mexc

## Overview

tg-signal-ingest ingests one selected Telegram channel, durably records its messages and recovery history, then parses eligible signals into guarded Spot order intents. The runtime separates ingestion, signal/trade lifecycle, exchange access, persistence, and owner operations. MEXC writes use the official CLI adapter, while REST supports read-only exchange data; the control bot is an operational interface, not a separate trading decision path. Relationships below follow the README and shown source references; several listed subsystems have no implementation excerpt, so their internal links are omitted.

Main entry points: [`tg_signal_ingest/trading/engine.py`](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/engine.py) (Intent engine), [`tg_signal_ingest/service.py`](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/service.py) (Live listener), [`tg_signal_ingest/trading/trade_manager.py`](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/trade_manager.py) (Trade lifecycle), [`tg_signal_ingest/control/service.py`](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/control/service.py) (Owner control bot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telegram ingestion"]
  node_listener["Live listener<br/>[service.py]"]
  node_telethon["Telegram client<br/>[telethon.py]"]
  node_backfill["Backfill and recovery<br/>[backfill.py]"]
  node_normalizer["Message normalization<br/>[normalize.py]"]
  node_processing["Processing queue<br/>[processing.py]"]
end

subgraph group_trade["Signal and trading"]
  node_parser["Signal parser<br/>[parser.py]"]
  node_engine["Intent engine<br/>[engine.py]"]
  node_risk["Risk controls<br/>[risk.py]"]
  node_trade_manager["Trade lifecycle<br/>[trade_manager.py]"]
  node_monitor["Market monitor<br/>[monitor.py]"]
end

subgraph group_storage["Durable state"]
  node_trade_store["Trading state<br/>[store.py]"]
  node_trade_records["Trade records<br/>[trade_store.py]"]
  node_message_repo["Message repository<br/>[repository.py]"]
  node_database[("SQLite database<br/>[db.py]")]
end

subgraph group_exchange["MEXC integration"]
  node_mexc_rest["Spot REST client<br/>[client.py]"]
  node_mexc_cli["Spot write adapter<br/>[cli.py]"]
end

subgraph group_operations["Operations and control"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_control["Owner control bot<br/>[service.py]"]
  node_bot_api["Control bot API<br/>[bot_api.py]"]
  node_notifications["Notification worker"]
end

node_telegram(("Telegram channel"))
node_mexc{{"MEXC Spot"}}
node_owner(("Owners and operator"))

node_telegram -->|"sends events"| node_telethon
node_telethon -->|"provides updates"| node_listener
node_listener -->|"runs recovery"| node_backfill
node_listener -->|"stores messages"| node_message_repo
node_backfill -->|"persists history"| node_message_repo
node_listener -->|"queues messages"| node_processing
node_processing -->|"normalizes content"| node_normalizer
node_engine -->|"parses signals"| node_parser
node_engine -->|"checks eligibility"| node_risk
node_engine -->|"records intents"| node_trade_store
node_engine -->|"advances trades"| node_trade_manager
node_trade_manager -->|"submits orders"| node_mexc_cli
node_mexc_cli -->|"writes Spot orders"| node_mexc
node_trade_manager -->|"reconciles read-only"| node_mexc_rest
node_mexc_rest -->|"queries Spot data"| node_mexc
node_monitor -->|"checks markets"| node_mexc_rest
node_message_repo -->|"persists messages"| node_database
node_trade_store -->|"persists intents"| node_database
node_trade_records -->|"uses trading state"| node_trade_store
node_owner -->|"operates service"| node_control
node_control -->|"sends bot requests"| node_bot_api
node_control -->|"uses settings"| node_config
node_engine -->|"appends events"| node_notifications
node_notifications -->|"delivers alerts"| node_owner
node_listener -->|"loads settings"| node_config

click node_listener "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/service.py"
click node_telethon "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/telethon.py"
click node_backfill "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/backfill.py"
click node_normalizer "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/normalize.py"
click node_processing "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/processing.py"
click node_parser "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/parser.py"
click node_engine "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/engine.py"
click node_risk "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/risk.py"
click node_trade_manager "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/trade_manager.py"
click node_monitor "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/monitor.py"
click node_trade_store "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/store.py"
click node_trade_records "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/trade_store.py"
click node_message_repo "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/repository.py"
click node_database "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/db.py"
click node_mexc_rest "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/mexc/client.py"
click node_mexc_cli "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/mexc/cli.py"
click node_config "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/config.py"
click node_control "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/control/service.py"
click node_bot_api "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/control/bot_api.py"
click node_notifications "https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/notification_dispatcher.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_listener,node_telethon,node_backfill,node_normalizer,node_processing toneBlue
class node_parser,node_engine,node_risk,node_trade_manager,node_monitor toneAmber
class node_trade_store,node_trade_records,node_message_repo,node_database toneMint
class node_mexc_rest,node_mexc_cli toneRose
class node_config,node_control,node_bot_api,node_notifications,node_telegram,node_mexc,node_owner toneIndigo
```

## Components

### Telegram ingestion

- [Live listener](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/service.py): `tg_signal_ingest/service.py`
- [Telegram client](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/telethon.py): `tg_signal_ingest/telethon.py`
- [Backfill and recovery](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/backfill.py): `tg_signal_ingest/backfill.py`
- [Message normalization](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/normalize.py): `tg_signal_ingest/normalize.py`
- [Processing queue](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/processing.py): `tg_signal_ingest/processing.py`

### Signal and trading

- [Signal parser](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/parser.py): `tg_signal_ingest/trading/parser.py`
- [Intent engine](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/engine.py): `tg_signal_ingest/trading/engine.py`
- [Risk controls](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/risk.py): `tg_signal_ingest/trading/risk.py`
- [Trade lifecycle](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/trade_manager.py): `tg_signal_ingest/trading/trade_manager.py`
- [Market monitor](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/monitor.py): `tg_signal_ingest/trading/monitor.py`

### Durable state

- [Trading state](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/store.py): `tg_signal_ingest/trading/store.py`
- [Trade records](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/trading/trade_store.py): `tg_signal_ingest/trading/trade_store.py`
- [Message repository](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/repository.py): `tg_signal_ingest/repository.py`
- [SQLite database](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/db.py): `tg_signal_ingest/db.py`

### MEXC integration

- [Spot REST client](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/mexc/client.py): `tg_signal_ingest/mexc/client.py`
- [Spot write adapter](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/mexc/cli.py): `tg_signal_ingest/mexc/cli.py`

### Operations and control

- [Runtime configuration](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/config.py): `tg_signal_ingest/config.py`
- [Owner control bot](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/control/service.py): `tg_signal_ingest/control/service.py`
- [Control bot API](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/control/bot_api.py): `tg_signal_ingest/control/bot_api.py`
- [Notification worker](https://github.com/20kevit/tele-mexc/blob/main/tg_signal_ingest/notification_dispatcher.py): `tg_signal_ingest/notification_dispatcher.py`

### Other components

- **Telegram channel**
- **MEXC Spot**
- **Owners and operator**

## Connections

- Telegram channel → Telegram client: sends events (evidence: `tg_signal_ingest/telethon.py`)
- Telegram client → Live listener: provides updates (evidence: `tg_signal_ingest/service.py`)
- Live listener → Backfill and recovery: runs recovery (evidence: `tg_signal_ingest/service.py`)
- Live listener → Message repository: stores messages (evidence: `tg_signal_ingest/service.py`)
- Backfill and recovery → Message repository: persists history (evidence: `tg_signal_ingest/backfill.py`)
- Live listener → Processing queue: queues messages (evidence: `tg_signal_ingest/service.py`)
- Processing queue → Message normalization: normalizes content
- Intent engine → Signal parser: parses signals (evidence: `tg_signal_ingest/trading/engine.py`)
- Intent engine → Risk controls: checks eligibility (evidence: `README.md`)
- Intent engine → Trading state: records intents (evidence: `tg_signal_ingest/trading/engine.py`)
- Intent engine → Trade lifecycle: advances trades (evidence: `README.md`)
- Trade lifecycle → Spot write adapter: submits orders (evidence: `README.md`)
- Spot write adapter → MEXC Spot: writes Spot orders (evidence: `README.md`)
- Trade lifecycle → Spot REST client: reconciles read-only (evidence: `README.md`)
- Spot REST client → MEXC Spot: queries Spot data (evidence: `tg_signal_ingest/mexc/client.py`)
- Market monitor → Spot REST client: checks markets (evidence: `README.md`)
- Message repository → SQLite database: persists messages (evidence: `tg_signal_ingest/repository.py`)
- Trading state → SQLite database: persists intents (evidence: `tg_signal_ingest/trading/store.py`)
- Trade records → Trading state: uses trading state (evidence: `tg_signal_ingest/trading/trade_store.py`)
- Owners and operator → Owner control bot: operates service (evidence: `README.md`)
- Owner control bot → Control bot API: sends bot requests (evidence: `tg_signal_ingest/control/service.py`)
- Owner control bot → Runtime configuration: uses settings (evidence: `tg_signal_ingest/control/service.py`)
- Intent engine → Notification worker: appends events (evidence: `README.md`)
- Notification worker → Owners and operator: delivers alerts (evidence: `README.md`)
- Live listener → Runtime configuration: loads settings (evidence: `tg_signal_ingest/service.py`)
