https://github.com/korovkincode/telesentinel-server
TeleSentinel-Server is a backend service for monitoring Telegram chats, analyzing messages using LLMs, and collecting users based on semantic filters.
https://github.com/korovkincode/telesentinel-server
celery fastapi python rabbitmq sqlalchemy
Last synced: 2 months ago
JSON representation
TeleSentinel-Server is a backend service for monitoring Telegram chats, analyzing messages using LLMs, and collecting users based on semantic filters.
- Host: GitHub
- URL: https://github.com/korovkincode/telesentinel-server
- Owner: korovkincode
- License: mit
- Created: 2026-04-02T21:57:04.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-04-11T14:51:56.000Z (3 months ago)
- Last Synced: 2026-04-11T15:05:20.862Z (3 months ago)
- Topics: celery, fastapi, python, rabbitmq, sqlalchemy
- Language: Python
- Homepage:
- Size: 104 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TeleSentinel
TeleSentinel-Server is a backend service for monitoring Telegram chats, analyzing messages using LLMs, and collecting users based on semantic filters.
## 🚀 Features
- Telegram channel parsing via user accounts (Telethon)
- Message analysis using LLM (score 1–100)
- Flexible task scheduling (one-time & recurring)
- Scalable background processing with Celery
- REST API with authentication (JWT)
- PostgreSQL as the single source of truth
---
## 🏗 Architecture
- **API**: FastAPI
- **Workers**: Celery
- **Queue Broker**: RabbitMQ
- **Database**: PostgreSQL
- **Telegram Client**: Telethon
- **LLM Provider**: OpenAI API (or compatible)
- **Scheduler**: Celery Beat
- **Containerization**: Docker
---
## 📦 Project Structure
```
app/
api/ # FastAPI routers
core/ # config, settings, security
exc/ # app exceptions
execution/ # execution logic
models/ # SQLAlchemy models
repositories/ # DB access layer
schemas/ # Pydantic
services/ # business logic
tasks/ # Celery Setup (worker.py, celery_app.py)
jobs/ # Celery Tasks (run_task.py, scheduler.py)
utils/ # helpers
migrations/ # Alembic
docker/ # Docker configs
```
---
## ⚙️ Setup
### 1. Clone repository
```bash
git clone
cd telesentinel
```
### 2. Environment variables
Create `.env` file:
```env
IS_PROD=0
SUPERUSER_LOGIN=superuser_login
SUPERUSER_PASSWORD=superuser_password
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_NAME=telesentinel
JWT_ALGORITHM=HS256
SECRET_KEY=your_secret
ACCESS_TOKEN_EXPIRES_MINUTES=60
REFRESH_TOKEN_EXPIRES_DAYS=7
REFRESH_TOKEN_COOKIE_NAME=your_cookie_name
OPENAI_API_KEY=your_key
```
---
### 3. Run with Docker
```bash
make build
make up
```
---
## 🔁 Services
* `api` – FastAPI app
* `worker` – Celery worker
* `beat` – Celery scheduler
* `db` – PostgreSQL
* `rabbitmq` – message broker
---
## 🔄 Core Flow
1. Scheduler creates `TaskRun`
2. Task is sent to Celery
3. Worker:
* fetches Telegram messages
* sends to LLM
* filters by threshold
* saves results
4. Updates `TaskRun` status
---
## 🧠 Key Design Decisions
* No Celery result backend → PostgreSQL is the source of truth
* Idempotent tasks
* Retry with exponential backoff
* Clear separation: API / Services / Repositories / Tasks
---
## ⚠️ Notes
* Telegram rate limits must be respected
* LLM usage should be optimized (cost & latency)
* Deduplication is required for messages
* Data retention: 14 days (cleanup job required)
---
## 🛠 Roadmap
* [ ] Auth & user management
* [ ] Telegram account integration
* [ ] Task management API
* [ ] Parsing worker
* [ ] LLM integration
* [ ] Result storage & querying
* [ ] Cleanup jobs
---