{
  "markdown": "<div align=\"center\">\n  <img src=\"image/logo/thelogo.png\" alt=\"Matplobbot Logo\" width=\"320\">\n  <h1>Matplobbot</h1>\n  <strong>Telegram bot and web dashboard for browsing study materials, rendering technical content, and tracking usage in real time.</strong>\n\n  <p align=\"center\">\n    <img src=\"https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white\" alt=\"Python\">\n    <img src=\"https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white\" alt=\"Docker\">\n    <img src=\"https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white\" alt=\"FastAPI\">\n    <img src=\"https://img.shields.io/badge/Aiogram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white\" alt=\"Aiogram\">\n    <img src=\"https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge&logo=postgresql&logoColor=white\" alt=\"PostgreSQL\">\n  </p>\n\n  <p align=\"center\">\n    <img src=\"https://img.shields.io/github/actions/workflow/status/Ackrome/matplobbot/ci-cd.yml?style=for-the-badge&label=Build&logo=github\" alt=\"Build status\">\n  </p>\n\n  <h3>Try it on Telegram</h3>\n  <p align=\"center\">\n    <a href=\"https://t.me/matplobbot\"><img src=\"https://img.shields.io/badge/STABLE_TELEGRAM_BOT-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white\" alt=\"Stable Telegram bot\"></a>\n    <a href=\"https://t.me/test_matplobbot\"><img src=\"https://img.shields.io/badge/DEVELOPMENT_TELEGRAM_BOT-ff8800?style=for-the-badge&logo=telegram&logoColor=white\" alt=\"Development Telegram bot\"></a>\n  </p>\n</div>\n\n## Overview\n\nMatplobbot is a multi-service platform built around a Telegram bot for technical and educational workflows. It combines interactive content browsing, Markdown and document rendering, university schedule tools, background processing, and a live analytics dashboard in one Docker-based stack.\n\nThe project currently includes:\n\n1. A Telegram bot built with `aiogram 3`.\n2. A scheduler service for notifications and background schedule checks.\n3. A FastAPI analytics dashboard with live stats and user drill-down pages.\n4. A Celery worker for heavy rendering tasks such as LaTeX, Mermaid, and document conversion.\n5. Supporting infrastructure via PostgreSQL, Redis, Docker Compose, and optional frontend/reverse-proxy services.\n\n## Key Features\n\n### Telegram Bot\n\n- Browse `matplobblib` modules and topics interactively with `/matp_all`.\n- Search `matplobblib` content with `/matp_search`.\n- Browse and search user-linked GitHub repositories with `/lec_all` and `/lec_search`.\n- Render LaTeX formulas to PNG with `/latex`.\n- Render Mermaid diagrams to PNG with `/mermaid`.\n- Convert Markdown into raw Markdown, HTML, or PDF output.\n- Save favorites, manage repositories, and configure personal settings from inline menus.\n- Use university schedule search, calendar navigation, daily and weekly views, and subscription-based notifications.\n\n### Schedule Tools\n\n- Search schedules by group, teacher, or auditorium.\n- Navigate dates through an inline calendar.\n- Receive next-day schedule notifications at a chosen time.\n- Get update alerts when lessons change, are added, or are cancelled.\n\n### Web Dashboard\n\n- View live usage stats over WebSockets.\n- See popular commands, text activity, action-type breakdowns, and activity trends.\n- Inspect user-specific pages with paginated history, filtering, and CSV export.\n- Stream the bot log into the dashboard for real-time monitoring.\n\n## Screenshots\n\n### Dashboard\n\n<div align=\"center\">\n  <img src=\"image/notes/Dashboard.png\" alt=\"Dashboard overview\" width=\"800\">\n</div>\n\n### User Details\n\n<div align=\"center\">\n  <img src=\"image/notes/User.png\" alt=\"User details page\" width=\"700\">\n</div>\n\n### Schedule Flow\n\n<div align=\"center\">\n  <img src=\"image/notes/schedule_en_1.png\" alt=\"Schedule search\" width=\"260\">\n  <img src=\"image/notes/schedule_en_2.png\" alt=\"Schedule results\" width=\"260\">\n  <img src=\"image/notes/schedule_en_3.png\" alt=\"Schedule day view\" width=\"260\">\n</div>\n\n<div align=\"center\">\n  <img src=\"image/notes/calendar_screenshot.png\" alt=\"Inline calendar\" width=\"320\">\n</div>\n\n## Quickstart\n\n### Prerequisites\n\n- Docker\n- Docker Compose\n\n### Minimal `.env` example\n\nCreate a `.env` file in the project root. This is a minimal example for local startup; your production setup may require additional variables.\n\n```env\nBOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11\nADMIN_USER_IDS=123456789,987654321\nGITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\nPOSTGRES_USER=user\nPOSTGRES_PASSWORD=password\nPOSTGRES_DB=matplobbot_db\nPOSTGRES_HOST=postgres\nPOSTGRES_PORT=5432\n```\n\n### Run locally\n\n```bash\ngit clone https://github.com/Ackrome/matplobbot.git\ncd matplobbot\ndocker compose up --build -d\n```\n\n### Access services\n\n- Telegram bot: available through Telegram after `BOT_TOKEN` is configured.\n- Analytics dashboard: `http://localhost:9583`\n- Static site frontend: `http://localhost:8080`\n- Scheduler health endpoint: `http://localhost:9584/health` for operational checks\n\n### Stop the stack\n\n```bash\ndocker compose down\n```\n\nTo remove named volumes as well:\n\n```bash\ndocker compose down -v\n```\n\n## Popular Commands\n\n| Command | Purpose |\n| :--- | :--- |\n| `/start` | Start the bot and initialize the main flow |\n| `/help` | Show the command/help menu |\n| `/schedule` | Search for a schedule by entity |\n| `/myschedule` | Show today's schedule for the saved entity |\n| `/matp_all` | Browse library content |\n| `/matp_search` | Search inside `matplobblib` |\n| `/lec_all` | Browse configured GitHub repositories |\n| `/lec_search` | Search Markdown files in a linked repository |\n| `/latex` | Render a LaTeX expression to PNG |\n| `/mermaid` | Render a Mermaid diagram to PNG |\n| `/favorites` | Open saved favorites |\n| `/settings` | Manage personal preferences and repositories |\n\n## Architecture\n\n### Tech Stack\n\n| Category | Technology |\n| :--- | :--- |\n| Backend | Python 3.11+ |\n| Bot | Aiogram 3 |\n| API | FastAPI, Uvicorn |\n| Database | PostgreSQL, asyncpg |\n| Queue | Celery, Redis |\n| Frontend | HTML, CSS, JavaScript, Chart.js |\n| Rendering | Pandoc, TeX Live, Mermaid CLI, Puppeteer |\n| Deployment | Docker, Docker Compose, Caddy, Nginx |\n\n### Project Structure\n\n```text\n.\n|-- bot/                  # Telegram bot logic, handlers, services, templates\n|-- fastapi_stats_app/    # Dashboard API, static assets, templates, routers\n|-- scheduler_app/        # Scheduled jobs and notification service\n|-- shared_lib/           # Shared database, schemas, services, tasks, i18n\n|-- main_site_frontend/   # Static frontend served by nginx\n|-- proxy/                # Proxy-related utilities/config\n|-- alembic/              # Database migrations\n|-- docker-compose.yml    # Local orchestration\n`-- docker-compose.prod.yml\n```\n\n### Rendering Flow\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Bot\n    participant Redis as Redis Broker\n    participant Worker as Celery Worker\n    participant DB as Database\n\n    User->>Bot: Sends /latex \\frac{a}{b}\n    Bot->>Redis: Enqueues render task\n    Bot-->>User: Sends temporary status message\n    Redis->>Worker: Delivers task\n    Worker->>Worker: Compiles output\n    Worker->>Redis: Stores result\n    Bot->>Redis: Retrieves result\n    Bot->>User: Sends rendered image\n    Bot->>DB: Caches result\n```\n\n### Architectural Notes\n\n- Shared logic lives in `shared_lib`, including database access, schemas, Redis integration, tasks, and localization.\n- Services are separated by responsibility and communicate through PostgreSQL and Redis.\n- Heavy rendering work is moved off the bot process to keep interactions responsive.\n- The stack is asynchronous end-to-end for API calls, database work, and bot interactions.\n\n## Development Notes\n\n### Database Migrations\n\nAlembic is used for schema changes.\n\n- In Docker Compose, migrations are applied automatically by the `migrator` service during startup.\n- Manual Alembic commands are mainly useful during development when you are changing models or preparing a new migration.\n\n```bash\nalembic revision --autogenerate -m \"Add new table\"\nalembic upgrade head\n```\n\n### Dependency Locking\n\n- `requirements.in` is the editable dependency source file for base bot/worker images.\n- `requirements.txt` is the lockfile consumed by Docker builds.\n- Regenerate the lockfile after changing `requirements.in`:\n\n```bash\npython -m pip install --upgrade pip pip-tools\npip-compile --resolver=backtracking --output-file requirements.txt requirements.in\n```\n\nRun the same dependency audit input builder used by CI before merging\nrequirement changes:\n\n```bash\npython scripts/build_audit_requirements.py\npython -m pip install pip-audit==2.10.1\npython -m pip_audit --strict -r audit-requirements.txt --ignore-vuln PYSEC-2024-277\n```\n\n`PYSEC-2024-277` is the only documented audit ignore; keep any new ignore next\nto the CI/Jenkins audit command with a concrete rationale.\n\n### Auto-Lint (Remote + Local)\n\n`.github/workflows/autolint-autofix.yml` runs on:\n- pull requests to `main`\n- direct pushes to `main`\n\nIt executes `pre-commit --all-files` and pushes auto-fixes back automatically.\nTo avoid infinite loops, the job skips commits authored by `github-actions[bot]`.\nThe autofix run is non-blocking: it commits all available automatic fixes even if\nsome lint issues still require manual refactoring.\nWorkflow files under `.github/workflows/` are intentionally excluded from auto-fix\ncommits due GitHub token permission limits for workflow updates.\n\nLocal hooks are still optional and useful for faster feedback:\n\n```bash\npython -m pip install --upgrade pip pre-commit\npre-commit install\npre-commit run --all-files\n```\n\n- Hook config lives in `.pre-commit-config.yaml`.\n- Lint/type tool settings live in `pyproject.toml`.\n\n### CI/CD Summary\n\nThe repository uses GitHub Actions for CI and image publishing, with Jenkins handling deployment orchestration. The shared library is versioned and published before updated service images are built and deployed.\n\n## Roadmap\n\n- [x] Integrate SQLAlchemy Core instead of raw SQL\n- [x] Add semantic search for project materials\n- [ ] Add plugin-based support for multiple universities\n- [ ] Support voice-driven schedule requests\n\n## Contributing\n\nContributions are welcome.\n\n1. Fork the repository.\n2. Create a feature branch.\n3. Commit your changes.\n4. Push the branch.\n5. Open a pull request.\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n",
  "bytes": 10431,
  "sha": "b3848e6b373262cdef6f311b6ebffd0ccc0b9c9f586ba6400fd5e5d34acc4961",
  "repo_slug": "ackrome/matplobbot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_ackrome_matplobbot_docs_index_md_ce32a677/readme"
}