How overklassniy/stankin_antispam_bot works
Project Type and Purpose
• This is a full‑stack anti‑spam system combining machine‑learning pipelines, a Telegram bot interface, and a web‑based administrative panel.
• Purpose: collect and preprocess chat data; train and host spam‑detection models; monitor and moderate incoming messages in Telegram; provide a browser UI for stats, logs, and model management.
High‑Level Components
a. Data Layer
• Raw dataset files under data/
• Preprocessing notebooks (ipynb/) and utils/preprocessing.py
• Model artifacts in models/
b. ML Pipeline
• Jupyter notebooks orchestrate ETL, model training, fine‑tuning (RuBERT, LR, NB, RF)
• utils/predictions.py for inference calls
c. Bot Service
• bot.py, run_bot.py launch an Aiogram‑based async Telegram bot
• utils/apis.py and utils/basic.py manage Telegram API interactions
d. Web Panel Service
• panel/app.py, auth.py, main.py define a Flask app with Flask‑SQLAlchemy and Flask‑Login
• panel/templates, static assets (CSS/JS) for UI
• run_panel.py or waitress to deploy
e. Configuration & Orchestration
• .env + config.json for environment variables and runtime settings
• run.py for combined or custom startup flows
f. External Services
• Telegram Bot API
• OpenAI API (optional ChatGPT enrichment)
• Combot Anti‑Spam (CAS) and LOLS via feature flags
Component Relationships & Interactions
• The Bot Service subscribes to incoming Telegram messages, invokes prediction routines (utils/predictions.py → loaded models), and, based on thresholds, deletes or mutes users and notifies an admin chat.
• The Web Panel reads/writes to the same database (Flask‑SQLAlchemy models in panel/db_models.py), exposing stats (spam counts, muted users) and allowing admin operations (model threshold tuning, session management).
• The ML Pipeline is mostly offline: it pulls raw data from data/, writes trained model files to models/, which are then loaded by both Bot Service and Web Panel for inference or display.
Architectural Patterns and Principles
• Layered architecture:
1. Data Ingestion & Preprocessing layer
2. Model Training & Storage layer
3. Service layer: Bot and Web Panel as separate micro‑services
4. Persistence layer: SQLite (instance/db.sqlite) or fallback
• Clear separation of concerns: utils/ for shared code; ipynb/ for experiments; panel/ for web UI; bot.py for realtime handling.
• Configuration‑driven: all runtime toggles and ports are set in config.json/.env.