Přidat telegram_bot/README.md

telegram_bot/README.md

@@ -0,0 +1,123 @@
+
+# Hate Speech Bot – Dokumentácia
+
+## 🧠 Opis aplikácie
+
+Hate Speech Bot je kompletný systém na automatickú detekciu nenávistnej reči v prostredí **Telegramu**. Aplikácia slúži ako monitorovací a analytický nástroj, ktorý umožňuje:
+
+- Automaticky **zachytiť a analyzovať správy** používateľov v skupinových chatoch.
+- V prípade detekcie nenávistného prejavu zaznamená informáciu o **používateľovi a správe do databázy**.
+- Vizualizuje porušovateľov cez **webové rozhranie** v reálnom čase.
+
+### Komponenty systému:
+1. **Telegram Bot**: Interceptuje správy v skupine a pomocou trénovaného LLM modelu klasifikuje, či ide o nenávistnú reč.
+2. **MySQL databáza**: Ukladá údaje o používateľoch, správach a čase incidentu.
+3. **Webová aplikácia (Flask)**: Zobrazuje tabuľku s porušeniami, automaticky aktualizovanú každých 5 sekúnd.
+
+---
+
+## 🧱 Zoznam použitých Docker kontajnerov
+
+| Kontajner                             | Popis |
+|--------------------------------------|-------|
+| `tetianamohorian/hate-speech-bot`    | Obsahuje Telegram bota, klasifikačný model (napr. fine-tuned BERT), a Flask frontend. |
+| `mysql:8`                             | Relačný databázový systém pre ukladanie záznamov o porušovateľoch. |
+
+---
+
+## ☸️ Zoznam Kubernetes objektov
+
+| Objekt                      | Popis |
+|----------------------------|-------|
+| `Namespace: botspace`      | Izolovaný priestor pre všetky objekty súvisiace s aplikáciou. |
+| `Deployment: bot-deployment` | Nasadzuje kontajner s botom. |
+| `Deployment: flask-web`    | Nasadzuje Flask webserver. |
+| `StatefulSet: mysql`       | Zabezpečuje perzistentný a konzistentný chod MySQL databázy. |
+| `PersistentVolume`         | Uchováva fyzické dáta databázy mimo podu. |
+| `PersistentVolumeClaim`    | Žiadosť o diskový priestor pre databázu. |
+| `Service: mysql`           | Vnútorná služba pre prístup k databáze. |
+| `Service: flask-service`   | Port-forward pre sprístupnenie webu. |
+| `ConfigMap: init-sql`      | Obsahuje SQL skripty na prvotnú inicializáciu schémy. |
+| `Secret: bot-secret`       | Bezpečné uloženie citlivých údajov ako je Telegram token. |
+
+---
+
+## 🌐 Virtuálne siete a úložiská
+
+- Všetky pody komunikujú cez internú sieť v `botspace`, čím sa znižuje riziko únikov údajov.
+- `PersistentVolume` pripojený k MySQL zaručuje zachovanie dát aj po reštarte podu.
+
+---
+
+## ⚙️ Konfigurácia kontajnerov
+
+- **Flask Web**: Beží na porte `5000`, ktorý je dostupný cez `flask-service`. Obnovuje sa každých 5 sekúnd pomocou JavaScriptu (AJAX `fetch`).
+- **Telegram Bot**: Spustený v samostatnom threade, číta správy, klasifikuje ich pomocou PyTorch modelu (alebo HuggingFace Transformers), a zapisuje výsledok do databázy.
+- **MySQL**: Inicializovaná pomocou `initContainer`, ktorý spustí skript uložený v `ConfigMap`.
+
+---
+
+## 🚀 Návod na použitie
+
+### 1. Príprava aplikácie:
+
+```bash
+./prepare-app.sh
+```
+
+- Zostaví Docker image s aplikáciou.
+- Pushne ho do Docker Hub repozitára.
+
+---
+
+### 2. Spustenie aplikácie:
+
+```bash
+./start-app.sh
+```
+
+- Vytvorí Kubernetes objekty.
+- Spustí port-forwarding pre Flask web na `localhost:8888`.
+
+---
+
+### 3. Pozastavenie (port-forward):
+
+```bash
+pkill -f "kubectl port-forward"
+```
+
+- Zastaví dočasný prístup cez port-forward.
+
+---
+
+### 4. Odstránenie aplikácie:
+
+```bash
+./stop-app.sh
+```
+
+- Zmaže celý `botspace`, vrátane databázy a všetkých služieb.
+
+---
+
+## 🌍 Prístup k webovej aplikácii
+
+Po úspešnom spustení aplikácie otvorte webový prehliadač:
+
+```
+http://localhost:8888
+```
+
+- Zobrazí sa tabuľka s informáciami o porušovateľoch.
+- Dáta sa aktualizujú automaticky každých 5 sekúnd bez potreby obnoviť stránku.
+
+---
+
+## 📦 Použité technológie
+
+- **Python, Flask, PyTorch / Transformers** – analýza a klasifikácia textov
+- **Docker, Docker Hub** – kontajnerizácia
+- **Kubernetes** – orchestrácia, škálovanie a sieťová izolácia
+- **MySQL** – relačné databázové úložisko
+- **JavaScript (AJAX)** – aktualizácia frontendu v reálnom čase