{"id":48919915,"url":"https://github.com/korovkincode/telesentinel-server","last_synced_at":"2026-04-17T04:35:02.596Z","repository":{"id":348798735,"uuid":"1199948311","full_name":"korovkincode/telesentinel-server","owner":"korovkincode","description":"TeleSentinel-Server is a backend service for monitoring Telegram chats, analyzing messages using LLMs, and collecting users based on semantic filters.","archived":false,"fork":false,"pushed_at":"2026-04-11T14:51:56.000Z","size":107,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-11T15:05:20.862Z","etag":null,"topics":["celery","fastapi","python","rabbitmq","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/korovkincode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T21:57:04.000Z","updated_at":"2026-04-11T14:43:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/korovkincode/telesentinel-server","commit_stats":null,"previous_names":["korovkincode/telesentinel-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/korovkincode/telesentinel-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korovkincode%2Ftelesentinel-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korovkincode%2Ftelesentinel-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korovkincode%2Ftelesentinel-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korovkincode%2Ftelesentinel-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/korovkincode","download_url":"https://codeload.github.com/korovkincode/telesentinel-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korovkincode%2Ftelesentinel-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31915432,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["celery","fastapi","python","rabbitmq","sqlalchemy"],"created_at":"2026-04-17T04:35:00.993Z","updated_at":"2026-04-17T04:35:02.591Z","avatar_url":"https://github.com/korovkincode.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TeleSentinel\n\n![Python](https://img.shields.io/badge/Python-3776AB?style=flat\u0026logo=python\u0026logoColor=white)\n![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=flat\u0026logo=fastapi\u0026logoColor=white)\n![Celery](https://img.shields.io/badge/Celery-6F42C1?style=flat\u0026logo=celery\u0026logoColor=white)\n![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-FF6600?style=flat\u0026logo=sqlalchemy\u0026logoColor=white)\n![Poetry](https://img.shields.io/badge/Poetry-4B0082?style=flat\u0026logo=python\u0026logoColor=white)\n![Ruff](https://img.shields.io/badge/Ruff-F4A261?style=flat\u0026logo=python\u0026logoColor=white)\n![Pytest](https://img.shields.io/badge/Pytest-FFD700?style=flat\u0026logo=pytest\u0026logoColor=black)\n![RabbitMQ](https://img.shields.io/badge/RabbitMQ-FF6600?style=flat\u0026logo=rabbitmq\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat\u0026logo=docker\u0026logoColor=white)\n![License: MIT](https://img.shields.io/badge/License-MIT-FFDD00?style=flat\u0026logo=github\u0026logoColor=black)  \n\nTeleSentinel-Server is a backend service for monitoring Telegram chats, analyzing messages using LLMs, and collecting users based on semantic filters.\n\n## 🚀 Features\n\n- Telegram channel parsing via user accounts (Telethon)\n- Message analysis using LLM (score 1–100)\n- Flexible task scheduling (one-time \u0026 recurring)\n- Scalable background processing with Celery\n- REST API with authentication (JWT)\n- PostgreSQL as the single source of truth\n\n---\n\n## 🏗 Architecture\n\n- **API**: FastAPI\n- **Workers**: Celery\n- **Queue Broker**: RabbitMQ\n- **Database**: PostgreSQL\n- **Telegram Client**: Telethon\n- **LLM Provider**: OpenAI API (or compatible)\n- **Scheduler**: Celery Beat\n- **Containerization**: Docker\n\n---\n\n## 📦 Project Structure\n\n```\n\napp/\n   api/            # FastAPI routers\n   core/           # config, settings, security\n   exc/            # app exceptions\n   execution/      # execution logic\n   models/         # SQLAlchemy models\n   repositories/   # DB access layer\n   schemas/        # Pydantic\n   services/       # business logic\n   tasks/          # Celery Setup (worker.py, celery_app.py)\n      jobs/        # Celery Tasks (run_task.py, scheduler.py)\n   utils/          # helpers\n\nmigrations/        # Alembic\ndocker/            # Docker configs\n\n```\n\n---\n\n## ⚙️ Setup\n\n### 1. Clone repository\n\n```bash\ngit clone \u003crepo_url\u003e\ncd telesentinel\n```\n\n### 2. Environment variables\n\nCreate `.env` file:\n\n```env\nIS_PROD=0\n\nSUPERUSER_LOGIN=superuser_login\nSUPERUSER_PASSWORD=superuser_password\n\nDB_USER=your_db_user\nDB_PASSWORD=your_db_password\nDB_NAME=telesentinel\n\nJWT_ALGORITHM=HS256\nSECRET_KEY=your_secret\n\nACCESS_TOKEN_EXPIRES_MINUTES=60\nREFRESH_TOKEN_EXPIRES_DAYS=7\nREFRESH_TOKEN_COOKIE_NAME=your_cookie_name\n\nOPENAI_API_KEY=your_key\n```\n\n---\n\n### 3. Run with Docker\n\n```bash\nmake build\nmake up  \n```\n\n---\n\n## 🔁 Services\n\n* `api` – FastAPI app\n* `worker` – Celery worker\n* `beat` – Celery scheduler\n* `db` – PostgreSQL\n* `rabbitmq` – message broker\n\n---\n\n## 🔄 Core Flow\n\n1. Scheduler creates `TaskRun`\n2. Task is sent to Celery\n3. Worker:\n   * fetches Telegram messages\n   * sends to LLM\n   * filters by threshold\n   * saves results\n4. Updates `TaskRun` status\n\n---\n\n## 🧠 Key Design Decisions\n\n* No Celery result backend → PostgreSQL is the source of truth\n* Idempotent tasks\n* Retry with exponential backoff\n* Clear separation: API / Services / Repositories / Tasks\n\n---\n\n## ⚠️ Notes\n\n* Telegram rate limits must be respected\n* LLM usage should be optimized (cost \u0026 latency)\n* Deduplication is required for messages\n* Data retention: 14 days (cleanup job required)\n\n---\n\n## 🛠 Roadmap\n\n* [ ] Auth \u0026 user management\n* [ ] Telegram account integration\n* [ ] Task management API\n* [ ] Parsing worker\n* [ ] LLM integration\n* [ ] Result storage \u0026 querying\n* [ ] Cleanup jobs\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkorovkincode%2Ftelesentinel-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkorovkincode%2Ftelesentinel-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkorovkincode%2Ftelesentinel-server/lists"}