Enterprise-grade CRM bot for salons, barbershops, and studios built with Clean Architecture. Clients self-book, masters manage schedules, owners get analytics — all inside Telegram. Open-core; commercial edition adds support and updates.
👉 Commercial edition:
CLIENT BOOKING FLOW
Main menu
Service selection
Master card
Date selection
Time selection
Payment method
Online payment
Upcoming bookings
TELEGRAM MINI APP — CLIENT INTERFACE
Home
Upcoming visits
Visit history
Choose a master
Choose a day
Choose a time
Check details
Booking confirmed
Booking cart
MASTER & ADMIN PANELS
Master schedule
Booking details (Master)
Admin analytics
Admin panel
Admin settings
- Python 3.11+
- Aiogram 3.x (FSM, Routers)
- SQLAlchemy + Alembic (asyncpg)
- PostgreSQL with advisory locks
- Docker & Docker Compose
- Pydantic for config/validation
- Structured logging
- Telegram Mini App (WebApp API)
- React + TypeScript (Client UI)
- FastAPI facade for WebApp
📂 Project Structure
.
├── bot
│ ├── app
│ │ ├── core # DB, Config, Logging
│ │ ├── domain # Models (SQLAlchemy)
│ │ ├── services # Business Logic (Gap search, analytics)
│ │ └── telegram # Handlers & Keyboards (Presentation)
│ └── migrations # Alembic versions
├── docker # Docker configs
└── docs # Documentation
- Clean Architecture & DDD-inspired layers (handlers, services, domain, repos, workers).
- Concurrency-safe bookings via
pg_advisory_xact_lock(no double bookings). - Smart scheduling: gap search, composite services, per-master durations, UTC-first with local render.
- Professional FSM + navigation stack: real Back behavior with preserved context.
- Payments & policies: holds during pay, cancellation/reschedule windows, Telegram Payments.
- Roles: Owner/Admin, Master, Client with clear permissions.
- Analytics: LTV, retention, no-show rate, revenue (real vs expected), CSV export.
- Background workers: reminders, hold cleanup, payment reconcile, notifications.
A modern Telegram Mini App for clients:
- Fast booking with a clean UI
- View upcoming & past bookings
- Cancel & reschedule without chat commands
- Works instantly inside Telegram (no installation)
Smart Booking Engine: Automatically finds gaps in schedules, supports multi-service bookings, and respects individual master speeds.
Double-Booking Protection: Uses PostgreSQL Advisory Locks to guarantee data integrity during concurrent requests.
Role-Based Access: Separate interfaces for Clients (booking), Masters (schedule management), and Admins (analytics & config).
Analytics Dashboard: Tracks LTV, Retention Rate, and No-Show statistics in real-time.
FSM & Navigation: Robust state machine with a navigation stack (Back button actually works correctly).
Clients can book and manage visits via a built-in Telegram Mini App:
- No commands, no learning curve
- Beautiful UI inside Telegram
- Booking in under 30 seconds
This drastically increases conversion and reduces admin workload.
# 1) Clone
git clone https://github.com/nazgool97/salon_bot.git
cd repo
# 2) Configure
cp .env.example .env
# 3) Run
docker-compose up -dThen talk to the bot with your token; edit .env for timezone, currency, policies, payment keys.
| Capability | Community (Open Core) | Commercial |
|---|---|---|
| Booking engine, FSM, navigation | ✅ | ✅ |
| Admin/Master/Client roles | ✅ | ✅ |
| Analytics (LTV, retention, no-show, revenue) | ✅ | ✅ |
| Payments & holds | ✅ | ✅ |
| Docker + Alembic + PostgreSQL | ✅ | ✅ |
| Support & updates | ✅ | ✅ |
| Production license | — | ✅ |
- Architecture: docs/ARCHITECTURE.md
- Deployment: docs/DEPLOY.md
- Developer Manual (deep dive): docs/DEVELOPER_MANUAL.md
- More payment providers and split payments.
- Multi-location policies.
- Advanced cohort analytics and churn signals.
- Inventory tracking for consumables.
- Open-core: free to explore, run locally, and learn.
- Commercial edition: production license, guided setup, updates, and support.
- Contact via the commercial link above for upgrades.
Built to be readable, testable, and safe under load: Clean Architecture, advisory locks, UTC everywhere, Alembic migrations, workers, and structured logging out of the box.
