StaffProBot Platform
Product Summary
StaffProBot is a platform for managing shifts, staff and payouts. Owners and managers maintain objects (locations) and schedules; employees work shifts; the system calculates pay, sends notifications and supports contracts and document templates. Access is via a Telegram bot or a web app (FastAPI); roles include owner, manager, employee, applicant and superadmin. The platform covers geolocation (PostGIS), calendar planning with time slots, contract templates and versions, payroll with adjustments and billing, reviews and ratings, and notifications with one-click login links to the web app.
Business Problem
Companies that run multiple locations and shift-based staff face manual scheduling, contract handling, pay calculation errors and poor visibility for employees. Coordinating shifts, contracts and pay across owners, managers and staff without a single system leads to double entry, disputes and delayed payments.
Solution
StaffProBot provides one backend for the Telegram bot and the web app. Objects have addresses and schedules; time slots define when shifts are needed; shifts assign employees. The web calendar supports drag-and-drop planning; the bot supports planning, reports and PIN-based web login. Contracts use templates and versions; a constructor (master) is in progress. Payroll is calculated from shifts with contract/slot/object rate priority; adjustments and payout schedules are supported. Notifications (shift, contract, offer, reminders) are sent to Telegram and web, each with an auto-login link to the relevant page. Reviews and ratings with moderation and appeals are implemented. CI/CD runs tests and deploys to production via GitHub Actions.
Key Capabilities
- **Roles and access:** Owner, manager, employee, applicant, superadmin; multiple roles per user; routing by prefix in `app.py` (/owner, /manager, /employee); JWT and Telegram auth; PIN from bot for web login.
- **Objects and shifts:** Objects with address and schedule; time slots (with max_employees); shifts; calendar (FullCalendar) with drag-and-drop; PostGIS for geolocation and “available for applicants”; filters and map.
- **Contracts and documents:** Templates, versions, constructor (in progress); contract conclusion and history; PDF generation (WeasyPrint).
- **Payroll and billing:** PayrollEntry, adjustments, rate priority (contract → slot → object); payout schedules; billing, tariffs, limits; YooKassa integration.
- **Reviews and ratings:** Reviews for employees and objects; moderation; appeals; reports.
- **Notifications:** Telegram and web; types (shift, contract, offer, reminders, etc.); auto-login URL in every Telegram message (NotificationActionService.get_action_url).
- **Telegram bot:** Planning, reports (including Excel), object selection by location, PIN for web, view shifts and offers.
- **DevOps:** Docker Compose (dev/prod), health checks, GitHub Actions (test, lint, security, deploy to 155.212.217.38), deployments table.
Architecture Overview
The system map (`doc/system-map.md`) describes the flow: **Roles** (owner, manager, employee, applicant, superadmin) use **Web** (FastAPI, Jinja2, Bootstrap 5, FullCalendar) or **Telegram Bot**. The **Core** (apps/web, apps/bot, shared/, domain/) uses **PostgreSQL (PostGIS)**, **Redis** and **RabbitMQ**. **Celery** runs payroll and scheduled tasks. **YooKassa** handles payments; **WeasyPrint/ReportLab** generate PDFs. Deploy is Docker Compose on production with Nginx and Let's Encrypt; CI/CD via GitHub Actions.
Integrations
| System | Role |
|--------|------|
| **PostgreSQL + PostGIS** | Main DB; geodata for objects and location checks |
| **Redis** | Cache, sessions |
| **RabbitMQ** | Message queue for Celery |
| **Celery** | Payroll jobs, reminders, scheduled tasks |
| **YooKassa** | Payments, billing |
| **Telegram Bot API** | Bot webhook, messages, PIN for web login |
| **MinIO/S3** | Document and media storage (optional Telegram storage) |
| **WeasyPrint / ReportLab** | PDF contracts |
Business Impact
- **Single system:** One place for objects, shifts, contracts and pay; less double entry and fewer errors.
- **Clear roles:** Owners, managers and employees have dedicated interfaces and permissions.
- **Transparent pay:** Rate priority and adjustments are defined; payout schedules and billing are supported.
- **Faster actions:** Notifications with direct links to the web app; bot for quick planning and reports.
- **Scalable foundation:** Four product modules in roadmap (shift marketplace, smart planning, auto pay, EDO); current codebase is the base for all.
Case Study
Case Study: staffprobot
Problem
Operations include multiple systems and manual transitions between them.
Engineering solution
Implemented a docs-driven integration pipeline with endlog-triggered updates and synchronized project artifacts.
Architecture
Project manifest + integrations manifests + knowledge extraction + static site generation.
Integrations
postgis, telegram-bot-api, yookassa
Business value
Faster updates of engineering portfolio, less manual documentation overhead, consistent cross-project visibility.
Engineering Log
Engineering log
Generated from `doc/changelog-entries.md`.
Run endlog pipeline to refresh this file.
2026 — Фаза 1: docs foundation и endlog протокол
Problem
Нужно унифицировать документацию и правила endlog для перехода к self-updating docs-driven платформе.
Engineering
Добавлены стандартизированные doc-файлы (ru/en), project-manifest.yaml, integration manifests и единый протокол #endlog в rules.
Business value
Проект подготовлен к автоматической синхронизации документации и генерации портфолио.
Tech
Markdown, YAML, Cursor rules.
Integrations
StaffProBot Platform
Product Summary
StaffProBot is a platform for managing shifts, staff and payouts. Owners and managers maintain objects (locations) and schedules; employees work shifts; the system calculates pay, sends notifications and supports contracts and document templates. Access is via a Telegram bot or a web app (FastAPI); roles include owner, manager, employee, applicant and superadmin. The platform covers geolocation (PostGIS), calendar planning with time slots, contract templates and versions, payroll with adjustments and billing, reviews and ratings, and notifications with one-click login links to the web app.
Business Problem
Companies that run multiple locations and shift-based staff face manual scheduling, contract handling, pay calculation errors and poor visibility for employees. Coordinating shifts, contracts and pay across owners, managers and staff without a single system leads to double entry, disputes and delayed payments.
Solution
StaffProBot provides one backend for the Telegram bot and the web app. Objects have addresses and schedules; time slots define when shifts are needed; shifts assign employees. The web calendar supports drag-and-drop planning; the bot supports planning, reports and PIN-based web login. Contracts use templates and versions; a constructor (master) is in progress. Payroll is calculated from shifts with contract/slot/object rate priority; adjustments and payout schedules are supported. Notifications (shift, contract, offer, reminders) are sent to Telegram and web, each with an auto-login link to the relevant page. Reviews and ratings with moderation and appeals are implemented. CI/CD runs tests and deploys to production via GitHub Actions.
Key Capabilities
- **Roles and access:** Owner, manager, employee, applicant, superadmin; multiple roles per user; routing by prefix in `app.py` (/owner, /manager, /employee); JWT and Telegram auth; PIN from bot for web login.
- **Objects and shifts:** Objects with address and schedule; time slots (with max_employees); shifts; calendar (FullCalendar) with drag-and-drop; PostGIS for geolocation and “available for applicants”; filters and map.
- **Contracts and documents:** Templates, versions, constructor (in progress); contract conclusion and history; PDF generation (WeasyPrint).
- **Payroll and billing:** PayrollEntry, adjustments, rate priority (contract → slot → object); payout schedules; billing, tariffs, limits; YooKassa integration.
- **Reviews and ratings:** Reviews for employees and objects; moderation; appeals; reports.
- **Notifications:** Telegram and web; types (shift, contract, offer, reminders, etc.); auto-login URL in every Telegram message (NotificationActionService.get_action_url).
- **Telegram bot:** Planning, reports (including Excel), object selection by location, PIN for web, view shifts and offers.
- **DevOps:** Docker Compose (dev/prod), health checks, GitHub Actions (test, lint, security, deploy to 155.212.217.38), deployments table.
Architecture Overview
The system map (`doc/system-map.md`) describes the flow: **Roles** (owner, manager, employee, applicant, superadmin) use **Web** (FastAPI, Jinja2, Bootstrap 5, FullCalendar) or **Telegram Bot**. The **Core** (apps/web, apps/bot, shared/, domain/) uses **PostgreSQL (PostGIS)**, **Redis** and **RabbitMQ**. **Celery** runs payroll and scheduled tasks. **YooKassa** handles payments; **WeasyPrint/ReportLab** generate PDFs. Deploy is Docker Compose on production with Nginx and Let's Encrypt; CI/CD via GitHub Actions.
Integrations
| System | Role |
|--------|------|
| **PostgreSQL + PostGIS** | Main DB; geodata for objects and location checks |
| **Redis** | Cache, sessions |
| **RabbitMQ** | Message queue for Celery |
| **Celery** | Payroll jobs, reminders, scheduled tasks |
| **YooKassa** | Payments, billing |
| **Telegram Bot API** | Bot webhook, messages, PIN for web login |
| **MinIO/S3** | Document and media storage (optional Telegram storage) |
| **WeasyPrint / ReportLab** | PDF contracts |
Business Impact
- **Single system:** One place for objects, shifts, contracts and pay; less double entry and fewer errors.
- **Clear roles:** Owners, managers and employees have dedicated interfaces and permissions.
- **Transparent pay:** Rate priority and adjustments are defined; payout schedules and billing are supported.
- **Faster actions:** Notifications with direct links to the web app; bot for quick planning and reports.
- **Scalable foundation:** Four product modules in roadmap (shift marketplace, smart planning, auto pay, EDO); current codebase is the base for all.
System Map
System map
StaffProBot Platform (staffprobot.ru)
```
Roles (Owner / Manager / Employee / Applicant / Superadmin)
│
├── Web (FastAPI) — /owner/*, /manager/*, /employee/*, /admin/*, /moderator/*
│ Jinja2, Bootstrap 5, FullCalendar, HTMX, vanilla JS
└── Telegram Bot (python-telegram-bot) — webhook, PIN for web login
│
▼
Core (apps/web, apps/bot, shared/, domain/)
│
├── Objects, TimeSlots, Shifts, Contracts, Templates
├── PayrollEntry, Adjustments, Billing, Tariffs
├── Reviews, Ratings, Notifications (web + Telegram, auto-login links)
├── Offers, Applications, Documents (MinIO/S3)
└── NotificationDispatcher, NotificationActionService
│
▼
PostgreSQL (PostGIS) + Redis + RabbitMQ
│
├── Celery (celery_worker, celery_beat) — payroll, reminders, scheduled tasks
├── YooKassa — payments
├── WeasyPrint / ReportLab — PDF contracts
└── Telegram Bot API
│
▼
Deploy: Docker Compose (prod), GitHub Actions → SSH pull, health check, deployments table
```