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: https://ko-fi.com/s/937c0881d1

• Python 3.11+
• Aiogram 3.x (FSM, Routers)
• SQLAlchemy + Alembic (asyncpg)
• PostgreSQL with advisory locks
• Docker & Docker Compose
• Pydantic for config/validation
• Structured logging

.
├── 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.

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).

# 1) Clone
git clone https://github.com/nazgool97/salon_bot.git
cd repo

# 2) Configure
cp .env.example .env

# 3) Run
docker-compose up -d

Then talk to the bot with your token; edit .env for timezone, currency, policies, payment keys.

• 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.