Telegram-admin-app-project

Both bots are production-ready: Alembic migrations from day one, 537 tests, CI running lint/type-check/security-scan on every push, Docker packaging for VPS/Proxmox deployment, and a single web admin panel instead of poking at .env files and a database by hand.

This README is the overview and quick start. For a beginner-friendly, step-by-step deployment walkthrough with FAQ and troubleshooting, see the Wiki — if you've never run a Docker container before, start there, not here. For deep implementation-level context and architecture decisions (written for contributors/maintainers, not end users), see CLAUDE.md, the repost bot's feature backlog in FEATURES.md, the phased implementation plan in IMPLEMENTATION_PLAN.md, and Guardian's own docs in guardian/GUARDIAN.md and guardian/GUARDIAN_FEATURES.md (these four are in Russian).

Contents

• What's inside
• Repost bot — features
• Guardian — AI group moderator
• Web admin panel
• Proxies
• Stack
• Quick start (no Docker)
• Docker deployment
• CLI commands
• Bot commands in Telegram
• Tests and code quality
• Backup
• Project structure
• Implementation status
• Support the project

What's inside

┌─────────────────────────────── Repost bot ────────────────────────────────┐
│                                                                             │
│  N Telegram channels                                                      │
│         │  Telethon (user session, reads without Bot API limits)          │
│         ▼                                                                 │
│  keyword filter → hash dedup → semantic dedup check (embeddings)          │
│         │                                                                 │
│         ▼                                                                 │
│  LLM rewrite (style profile per post type) + source enrichment (Brave)    │
│  + RU/EN version comparison + auto cover image (Unsplash/ComfyUI)         │
│         │                                                                 │
│         ▼                                                                 │
│  manual moderation via DM (✅/❌/✏️) OR scheduled auto-posting             │
│         │                                                                 │
│         ▼                                                                 │
│  publish to N groups → collect stats → auto-digest / native ads /         │
│  smart scheduling / growth tracker                                        │
└─────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────── Guardian ──────────────────────────────────┐
│                                                                             │
│  New member → CAPTCHA (math/button/question) → muted until answered →     │
│               welcome message with rules / auto-kick on timeout            │
│                                                                             │
│  Every message → anti-flood → link whitelist → stop words →               │
│                   suspicion heuristics → AI classifier                     │
│                   (only for the suspicious ~20% — saves tokens)            │
│                                                                             │
│  Violations → escalating warns (mute → kick → ban) → log channel          │
│  Join spike → anti-raid (chat lockdown) → auto-unlock                     │
│  30 clean days → auto-trust (bypasses filters)                            │
└─────────────────────────────────────────────────────────────────────────┘

Both processes live in one repository but are independent bots — their own tokens, their own databases (tg_repost.db / guardian.db), their own Alembic migration chains. One crashing or being redeployed doesn't touch the other. Both are managed from a single web panel.

Repost bot — features

Content collection and quality

• Reads without Bot API limits — Telethon on a user session sees any public/accessible channel, not just ones where the bot is an admin.
• Keyword filtering — global or per-channel stop-/required-words, applied before a post ever enters the queue.
• Two-layer deduplication — fast exact-match hashing plus optional semantic dedup via embeddings (catches paraphrased copies from other channels).
• Rewrite style profiles — news / opinion / instruction / humor, each with its own prompt template, per-source or auto-selected by the LLM.
• Source enrichment — Brave Search finds 2-3 relevant links (RU + EN) on the post's topic, the LLM picks the best ones, a "📚 Sources" block is appended — builds audience trust and guards against misinformation accusations.
• Version comparison — if Russian and English sources disagree on the story, the post is honestly flagged "⚠️ conflicting accounts".
• Auto cover images — if a post has no media, generate one via the Unsplash API (fast, free) or a local ComfyUI instance (unique AI generation).

Publishing and growth

• Flexible moderation — manual approval via DM buttons / full autopilot / drip-posting on time slots, any combination.
• Multi-channel publishing — per-source target overrides (Source.target_chat_ids), not a blanket "everything to every group".
• Smart scheduling — analyzes view history to find your audience's peak hours and recommends (or auto-applies) a shift in posting slots.
• Auto-digest — once a week the LLM compiles a summary of the best posts.
• Native ads — every Nth post organically weaves in an ad brief in the channel's own voice, rotating through briefs.
• Growth tracker — subscriber-count snapshots plus per-style post counts, so you can see what's actually growing the channel.
• Negative-reaction auto-response — counts 👎/💩/😡 reactions, notifies the owner and optionally deletes the post past a threshold (with brigading protection — a cap on auto-deletes per hour).

Reliability and scale

• Anti-ban mechanics — jitter between requests, hourly read limits — reduce the risk of the Telethon user session getting restricted.
• Multiple Telethon session rotation — balances source reading across accounts as the channel count grows, with a separate rate limiter per session.
• Post status machine — explicit transitions new → filtered_out | duplicate → rewriting → rewritten → pending_approval → approved | rejected → posted | failed, every transition logged.
• Retry with exponential backoff on every network call (Telegram, LLM, search).
• MTProto/SOCKS5 proxy support — Telethon (user session) goes through an MTProto proxy, the Bot API (posting/moderation) through SOCKS5; see Proxies below — and read the Wiki's Proxy Guide before you configure this, there's an important limitation.

Guardian — AI group moderator

A separate bot on aiogram. Its job isn't to review content — it's to protect the real people in your group from spam, bots, and toxicity while your audience grows.

New-member verification

• Muted immediately on join → CAPTCHA (math / "I'm not a robot" button / channel-topic question) → restrictions lifted on a correct answer.
• No answer within N minutes → auto-kick.
• The "who answered first" race and "who is actually the new member vs. who invited them" confusion are closed via explicit user_id addressing rather than aiogram FSM context (a real security bug found and fixed — see commit history).
• Profile analysis — no username/photo, suspicious bio, brand-new account → a stronger CAPTCHA for risky profiles (never an auto-ban based on profile alone — that would be too aggressive).

Spam filter — three modes to choose from

The AI classifier is fail-open: any error, timeout, or invalid JSON is treated as "let it through", never as "delete" — when unsure, the bot never cuts a legitimate message.

Moderation and protection

• Link whitelist filter, including links hidden behind text (text_link entities).
• Anti-flood — message-rate limit per window plus repeated-duplicate detection.
• Warn system with escalation to the highest threshold reached (mute → kick → ban), scheduled TTL auto-reset of warns.
• Anti-raid — a join spike locks down the whole chat's permissions (restoring the *pre