1 · What BridgeBot is
A multi-platform bridge: it connects a contact on one messenger to a contact on another so they can talk without switching apps. It also proxies content (YouTube, Instagram, X) for networks where those sites are blocked, and exposes a web app, a public web-chat, and wizard bots on Telegram & Bale.
2 · Top-level topology
The hub owns the bridge logic and the single source of truth (group_mapping). Sending is a seam (deliver()) that puts jobs on the broker; workers — local or remote — drain the queues and do the actual send.
3 · How a message crosses platforms
- 1A message arrives on a platform (e.g. a WhatsApp DM hits /internal/wa-message, or a Bale group message hits the Bale client).
- 2The bridge ensures a paired group exists (get_or_create_contact_group) and records it in group_mapping.
- 3The router looks up the mapping and decides the destination platform + target id.
- 4deliver(platform, to, text) puts a job on q:<platform>.out.
- 5A worker in that platform's pool (any server) drains the queue and performs the real send.
4 · Each platform
| Platform | Library / transport | Login | Multi-account | Module |
|---|---|---|---|---|
| ✈️ Telegram | Telethon (MTProto) | phone + code | workers/sessions | tg/client.py |
| 🟢 Bale | aiobale + bot REST | phone + code | workers/sessions | bale/client.py · bale/api.py |
| instagrapi (private API) | sessionid cookie | ✓ rotating pool + proxy | instagram/bridge.py · features/instagram.py | |
| whatsapp-web.js (Node sidecar) | QR scan | one linked device / sidecar | wa-bridge/index.js | |
| 🟠 Rubika | rubpy | phone + code | workers/sessions | rubika/client.py |
| 🟡 Eitaa | eitaayar bot API | bot token | tokens | eita/__init__.py |
User picks a contact in the bot/web wizard → hub creates a paired group on each side (or a web-chat token) → stores both directions in group_mapping → sends an invitation (group link, or the web-chat link for Instagram). Afterwards every message flows both ways via the router.
Because IG DMs are fragile from a datacenter IP, the IG bridge sends the contact a one-time greeting DM containing a web-chat link (/chat/<token>). The real conversation happens in our web-chat, bridged to the paired TG group — so no ongoing IG DM traffic is needed.
5 · Running platforms on other servers
main.py = the hub (one server). worker.py <platform> = a worker (any server). Both point at the same REDIS_URL.
Raise or lower workers per platform without a restart:
Or run worker.py bale on more servers — they all pull from q:bale.out and split the load. That's horizontal scale + multi-account (a different account per worker).
6 · Code map
- clients.py — live client objects (tg, bale, bots)
- state.py — the one shared state dict + WS broadcast
- db.py — SQLite schema + all persistence (mappings, messages, prefs, names, subs)
- config.py — env vars
- broker/queue.py — work queues (in-mem / Redis)
- broker/bus.py — pub/sub channels
- broker/route.py — inbound→outbound routing rules
- workers.py — scalable per-platform pools
- worker.py — standalone per-server entrypoint
- tg/client.py · bale/client.py · bale/api.py
- instagram/bridge.py · rubika/client.py · eita/
- wa-bridge/index.js (Node)
- features/youtube.py · tools.py · instagram.py
- features/telegram.py · subscriptions.py · flags.py
- api/youtube.py — public /watch proxy + player API
- (more route groups migrating out of main.py incrementally)
- login.py — per-server multi-account login
- broadcast.py — channel broadcast/advertisement
- service_manager.py — PyQt desktop control panel
Every platform now lives in its own folder and runs individually. The shared foundation (clients/state/db) and broker/workers were extracted first, then each platform's connection loop + inbound path moved out behind a dependency-injection seam: start_telegram + its 4 event handlers → tg/client.py; start_bale (the ~1,000-line aiobale WS loop + binary frame parser) → bale/client.py; start_rubika → rubika/client.py; start_instagram → instagram/bridge.py; WhatsApp sidecar + inbound → whatsapp/sidecar.py & whatsapp/inbound.py. The hub keeps only thin wrappers that inject deliver/submit_inbound as callables (no module imports main). Both PolBot onboarding wizards also moved out — the Telegram wizard (start_tg_bot + bridge creation + media cache) → tg/bot.py (6 injected seams), and the Bale wizard (start_bale_bot + _handle_bale_bot_update REST poller) → bale/bot.py (4 injected seams). The dispatch core (deliver/deliver_media/submit_inbound + inbound router + worker-pool setup) then moved to a self-contained dispatch.py — the keystone that lets route blueprints call deliver without importing main. main.py shrank from 10,091 → ~4,220 lines. Route blueprints have started landing on top of that seam: api/otp.py (OTP service) and api/x.py (X/Twitter explore) join api/youtube.py, using the shared app.config['ASYNC_LOOP'] convention. The remaining /me/api and /admin/api route groups migrate the same way. Every module is documented file-by-file in docs/CODE_REFERENCE.md.