{"id":30145159,"url":"https://github.com/shamspias/plugbot","last_synced_at":"2025-08-11T08:09:59.930Z","repository":{"id":308766103,"uuid":"622338519","full_name":"shamspias/PlugBot","owner":"shamspias","description":"PlugBot connects multiple Dify bots and Telegram in one seamless platform. Easily manage endpoints, API keys, and bot tokens—all from a sleek dashboard. Power up your workflows with PlugBot’s unified, intuitive interface.","archived":false,"fork":false,"pushed_at":"2025-08-07T19:49:17.000Z","size":104,"stargazers_count":33,"open_issues_count":1,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-07T20:26:19.537Z","etag":null,"topics":["ai","artificial-intelligence","chatbot","chatbots","dify","dify-client","discord-bot","machine-learning","nlp","python","telegrambot"],"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/shamspias.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2023-04-01T20:15:11.000Z","updated_at":"2025-08-07T19:49:20.000Z","dependencies_parsed_at":"2025-08-07T20:36:39.187Z","dependency_job_id":null,"html_url":"https://github.com/shamspias/PlugBot","commit_stats":null,"previous_names":["shamspias/gpt-document-trained-chatbot-builder"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/shamspias/PlugBot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2FPlugBot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2FPlugBot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2FPlugBot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2FPlugBot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shamspias","download_url":"https://codeload.github.com/shamspias/PlugBot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2FPlugBot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269850366,"owners_count":24485177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"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":["ai","artificial-intelligence","chatbot","chatbots","dify","dify-client","discord-bot","machine-learning","nlp","python","telegrambot"],"created_at":"2025-08-11T08:09:59.057Z","updated_at":"2025-08-11T08:09:59.889Z","avatar_url":"https://github.com/shamspias.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/plugbot-logo.png\" alt=\"PlugBot Logo\" width=\"160\"/\u003e\n\u003c/p\u003e\n\n# PlugBot ⚡\n\n_Easily bridge any number of Dify apps to Telegram bots_\n\n[![Docker ready](https://img.shields.io/badge/docker-ready-2496ed?logo=docker\u0026logoColor=white)](https://hub.docker.com/)\n[![GitHub stars](https://img.shields.io/github/stars/shamspias/plugbot?style=social)](https://github.com/shamspias/plugbot/stargazers)\n[![Build status](https://img.shields.io/github/actions/workflow/status/shamspias/plugbot/ci.yml)](../../actions)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n\n\u003e **PlugBot** lets you manage unlimited **Dify** applications  \n\u003e (chat, agent, chat-flow, workflow) and expose each one through a Telegram bot—  \n\u003e no extra glue code, all in a polished Next.js dashboard.\n\n---\n\n## Table of Contents\n\n1. [Features](#features)\n2. [Tech stack](#tech-stack)\n3. [Architecture](#architecture)\n4. [Quick start (Docker)](#quick-start-docker)\n5. [Manual installation](#manual-installation-without-docker)\n6. [Configuration](#configuration)\n7. [Usage](#usage)\n8. [Development workflow](#development-workflow)\n9. [Testing](#testing)\n10. [Security policy](#security-policy)\n11. [Contributing](#contributing)\n12. [License](#license)\n13. [Acknowledgements](#acknowledgements)\n\n---\n\n## Features\n\n| \u0026nbsp;                      | Capability                                                                   |\n|-----------------------------|------------------------------------------------------------------------------|\n| 🔗 **Multi-endpoint**       | Point to any number of Dify servers—just paste *endpoint* + *API key*.       |\n| 🤖 **Multi-bot**            | Each Dify app can be paired with its own Telegram bot token.                 |\n| 🖥 **Dashboard**            | Start / stop / restart, live health-check, conversation counters.            |\n| 🔄 **Streaming \u0026 blocking** | Toggle real-time streaming or batch responses per bot.                       |\n| 🔐 **Secrets at rest**      | API keys \u0026 bot tokens encrypted with Fernet AES-128 (configurable).          |\n| 🐳 **One-command deploy**   | `docker compose up -d --build` brings up Postgres, Redis, backend, frontend. |\n| 🚀 **Hot-reload dev**       | Works equally well outside Docker for fast local hacking.                    |\n| ✅ **CI-ready**              | Unit tests + pre-commit hooks + conventional commits.                        |\n\n---\n\n## Tech stack\n\n* **Backend** – FastAPI × SQLAlchemy × Alembic × Pydantic v2\n* **Realtime** – python-telegram-bot v20 (long-polling or web-hooks)\n* **Frontend** – Next.js 14, React 18, Tailwind CSS, Lucide icons\n* **Data** – PostgreSQL 16, Redis 7\n* **Packaging** – Docker multistage images, docker-compose v3.9\n\n---\n\n## Architecture\n\n```\n\n┌────────────┐     (REST)     ┌──────────────┐\n│  Frontend  │ ─────────────► │   FastAPI    │ ─┐\n│  Next.js   │                │  PlugBot API │  │          ┌──────────────┐\n└────────────┘                └──────────────┘  │ (HTTPS)  │   Dify API   │\n│◄────────►│ (one or many)│\n(WebSocket / HTTP)            ▲              │          └──────────────┘\n│              │\n│  (async I/O) │\n│              ▼\n┌────────────────────┐\n│ python-telegram-bot │  (long-poll / web-hook)\n└────────────────────┘\n\n````\n\n---\n\n## Quick start (Docker)\n\n```bash\n# 1 — clone \u0026 enter the repo\ngit clone https://github.com/shamspias/plugbot.git\ncd plugbot\n\n# 2 — create env files\ncp .env.example .env\n\n# 3 — edit the new .env files (SECRET_KEY, ENCRYPTION_KEY, etc.)\n\n# 4 — build \u0026 run everything\ndocker compose up -d --build\n```\n\n| Service     | Host URL                                                 | Inside-container URL    |\n|-------------|----------------------------------------------------------|-------------------------|\n| Frontend UI | [http://localhost:3514](http://localhost:3514)           | `http://localhost:3000` |\n| FastAPI API | [http://localhost:8531/docs](http://localhost:8531/docs) | `http://localhost:8000` |\n| PostgreSQL  | `localhost:5432` *(optional)*                            | `postgres://db:5429`    |\n| Redis       | n/a *(internal only)*                                    | `redis://redis:6387`    |\n\n*Back-end migrations run automatically on first boot.*\n\n---\n\n## Manual installation (without Docker)\n\n### Prerequisites\n\n| Stack      | Version |\n|------------|---------|\n| Python     | 3.11    |\n| Node       | 18      |\n| PostgreSQL | ≥ 14    |\n| Redis      | ≥ 6     |\n\n### Backend\n\n```bash\ncd backend\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\n\ncp .env.example .env   # then edit secrets \u0026 DB URL\n\nalembic upgrade head   # create tables\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n### Frontend\n\n```bash\ncd ../frontend\nnpm install\ncp .env.example .env           # adjust NEXT_PUBLIC_API_URL if needed\nnpm run dev                    # http://localhost:3514\n```\n\n---\n\n## Configuration\n\nAll settings are environment variables.\nThe most important ones are:\n\n| Variable              | Where    | Default                                          | Purpose                                   |\n|-----------------------|----------|--------------------------------------------------|-------------------------------------------|\n| `SECRET_KEY`          | backend  | *(none)*                                         | JWT signing \u0026 CSRF                        |\n| `ENCRYPTION_KEY`      | backend  | *(none)*                                         | 32-char Fernet key for encrypting secrets |\n| `DATABASE_URL`        | backend  | `postgresql://postgres:postgres@db:5432/plugbot` | SQLAlchemy DSN                            |\n| `REDIS_URL`           | backend  | `redis://redis:6387/0`                           | Caching / queues                          |\n| `NEXT_PUBLIC_API_URL` | frontend | `http://localhost:8531/api/v1`                   | Point UI to the API                       |\n\n---\n\n## Usage\n\n1. **Open the dashboard** → click **“Add Bot”**.\n2. Paste your **Dify endpoint** and **API key**.\n3. *(Optional)* paste a Telegram **bot token** from **@BotFather**.\n4. Hit **Create** – PlugBot verifies the Dify server, starts the Telegram bot,\n   and you’re good to go! 🎉\n\n---\n\n## Development workflow\n\n| Task                       | Command                                          |\n|----------------------------|--------------------------------------------------|\n| Lint / format (pre-commit) | `pre-commit run --all-files`                     |\n| Python hot-reload          | `uvicorn app.main:app --reload`                  |\n| Next.js hot-reload         | `npm run dev`                                    |\n| Generate Alembic revision  | `alembic revision --autogenerate -m \"my change\"` |\n\n\u003e **Tip**: `pre-commit install` will auto-run *black*, *ruff*, *isort*, Prettier, ESLint, etc. on every commit.\n\n---\n\n## Testing\n\n```bash\n# Docker\ndocker compose exec backend pytest -q\n# or local venv\npytest\n```\n\nFront-end tests live under `frontend/src/__tests__/` (React Testing Library).\n\n---\n\n## Security policy\n\nPlease report vulnerabilities privately by opening a “Security advisory” on\nGitHub or emailing *[info@shamspias.com](mailto:info@shamspias.com)*.\nWe follow [responsible disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure) and aim to patch within **30\ndays**.\n\n---\n\n## Contributing\n\nPull requests are welcome!\nRead the [**CONTRIBUTING.md**](CONTRIBUTING.md) guide for branching, coding style,\ncommit messages, and CI checklist.\n\n---\n\n## License\n\nPlugBot is released under the [MIT license](LICENSE).\n\n---\n\n## Acknowledgements\n\n* [Dify](https://github.com/langgenius/dify) – powerful LLM app platform\n* [FastAPI](https://fastapi.tiangolo.com/) – modern, fast web framework\n* [Next.js](https://nextjs.org/) – React framework for the web\n* [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) – Telegram API wrapper\n* All [contributors](../../graphs/contributors) – thank you! 🙏","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshamspias%2Fplugbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshamspias%2Fplugbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshamspias%2Fplugbot/lists"}