# raiyaxkrash/zapisflow architecture

> Architecture diagram of the GitHub repository raiyaxkrash/zapisflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raiyaxkrash/zapisflow
- Repository: https://github.com/raiyaxkrash/zapisflow

## Overview

ZapisFlow is a multitenant SaaS for beauty-service bookings and studio management through Telegram bots. Clients enter through a tenant bot, browse services and available slots, then create a booking and handle its deposit; masters manage bookings and studio operations in the same bot. A platform manager bot provisions tenant bots and subscriptions. Webhook intake, tenant routing, persistence, and scheduled work support these user-facing flows. README documents the overall architecture; several domain handlers and background jobs are represented by their tree paths because their source was not sampled.

Main entry points: [`app/bot/handlers/client/booking.py`](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/client/booking.py) (Client booking flows), [`app/bot/handlers/admin/appointments.py`](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/admin/appointments.py) (Master admin CRM), [`app/web/app.py`](https://github.com/raiyaxkrash/zapisflow/blob/main/app/web/app.py) (Webhook ingestion), [`app/services/bot_registry.py`](https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/bot_registry.py) (Tenant bot registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Bot Runtime"]
  node_webhook["Webhook ingestion<br/>[app.py]"]
  node_registry["Tenant bot registry<br/>[bot_registry.py]"]
  node_dispatch["Shared bot dispatcher<br/>[bot_instance.py]"]
  node_tenant["Tenant context<br/>[tenant_context.py]"]
end

subgraph group_platform["Platform Management"]
  node_manager["Platform manager bot<br/>[handlers.py]"]
  node_provisioning["Bot provisioning"]
  node_crypto["Token encryption<br/>[token_crypto.py]"]
  node_subscriptions["Subscription lifecycle"]
end

subgraph group_client["Client Booking"]
  node_client_handlers["Client booking flows<br/>[booking.py]"]
  node_services["Service catalog<br/>[services.py]"]
  node_slots["Availability calculation<br/>[slot_engine.py]"]
  node_booking["Booking lifecycle<br/>[booking_service.py]"]
  node_client_payments["Client deposit flow<br/>[payment.py]"]
  node_client_account["Appointments and portfolio<br/>[my_appointments.py]"]
end

subgraph group_admin["Studio Management"]
  node_admin_handlers["Master admin CRM<br/>[appointments.py]"]
  node_admin_schedule["Schedule management<br/>[calendar_mgmt.py]"]
  node_admin_payments["Payment review<br/>[payments.py]"]
  node_analytics["Business analytics<br/>[analytics.py]"]
  node_broadcast["Client broadcasts"]
end

subgraph group_backend["Persistence and Jobs"]
  node_scheduler["Scheduled jobs<br/>[scheduler.py]"]
  node_reminders["Booking reminders<br/>[reminder_worker.py]"]
  node_repositories["Data repositories"]
  node_database[("PostgreSQL data<br/>[session.py]")]
  node_redis[("Redis services")]
end

node_telegram(("Telegram users"))
node_telegram_api["Telegram API"]

node_telegram -->|"sends updates"| node_webhook
node_webhook -->|"resolves tenant bot"| node_registry
node_webhook -->|"routes manager updates"| node_manager
node_registry -->|"provides bot"| node_dispatch
node_dispatch -->|"establishes tenant"| node_tenant
node_tenant -->|"routes client updates"| node_client_handlers
node_tenant -->|"routes admin updates"| node_admin_handlers
node_manager -->|"provisions bots"| node_provisioning
node_provisioning -->|"protects bot tokens"| node_crypto
node_manager -->|"manages subscriptions"| node_subscriptions
node_client_handlers -->|"browses services"| node_services
node_client_handlers -->|"requests availability"| node_slots
node_client_handlers -->|"creates booking"| node_booking
node_booking -.->|"persists booking"| node_repositories
node_client_handlers -->|"continues to deposit"| node_client_payments
node_client_handlers -->|"views appointments"| node_client_account
node_admin_handlers -->|"manages schedule"| node_admin_schedule
node_admin_handlers -->|"reviews deposits"| node_admin_payments
node_admin_handlers -->|"reviews performance"| node_analytics
node_admin_handlers -.->|"sends broadcasts"| node_broadcast
node_scheduler -->|"runs reminder jobs"| node_reminders
node_reminders -->|"loads booking data"| node_repositories
node_scheduler -.->|"uses database"| node_database
node_scheduler -->|"coordinates jobs"| node_redis
node_repositories -.->|"reads and writes"| node_database
node_webhook -->|"deduplicates updates"| node_redis
node_registry -->|"loads bot records"| node_database
node_registry -.->|"uses bot sessions"| node_telegram_api

click node_webhook "https://github.com/raiyaxkrash/zapisflow/blob/main/app/web/app.py"
click node_registry "https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/bot_registry.py"
click node_manager "https://github.com/raiyaxkrash/zapisflow/blob/main/app/manager_bot/handlers.py"
click node_provisioning "https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/bot_provisioning_service.py"
click node_crypto "https://github.com/raiyaxkrash/zapisflow/blob/main/app/core/token_crypto.py"
click node_subscriptions "https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/subscription_service.py"
click node_dispatch "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/bot_instance.py"
click node_tenant "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/middlewares/tenant_context.py"
click node_client_handlers "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/client/booking.py"
click node_services "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/client/services.py"
click node_slots "https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/slot_engine.py"
click node_booking "https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/booking_service.py"
click node_client_payments "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/client/payment.py"
click node_client_account "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/client/my_appointments.py"
click node_admin_handlers "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/admin/appointments.py"
click node_admin_schedule "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/admin/calendar_mgmt.py"
click node_admin_payments "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/admin/payments.py"
click node_analytics "https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/admin/analytics.py"
click node_broadcast "https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/broadcast_service.py"
click node_scheduler "https://github.com/raiyaxkrash/zapisflow/blob/main/app/scheduler/scheduler.py"
click node_reminders "https://github.com/raiyaxkrash/zapisflow/blob/main/app/scheduler/jobs/reminder_worker.py"
click node_repositories "https://github.com/raiyaxkrash/zapisflow/blob/main/app/repositories/appointment_repository.py"
click node_database "https://github.com/raiyaxkrash/zapisflow/blob/main/app/database/session.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webhook,node_registry,node_dispatch,node_tenant,node_telegram toneBlue
class node_manager,node_provisioning,node_crypto,node_subscriptions toneAmber
class node_client_handlers,node_services,node_slots,node_booking,node_client_payments,node_client_account,node_telegram_api toneMint
class node_admin_handlers,node_admin_schedule,node_admin_payments,node_analytics,node_broadcast toneRose
class node_scheduler,node_reminders,node_repositories,node_database,node_redis toneIndigo
```

## Components

### Bot Runtime

- [Webhook ingestion](https://github.com/raiyaxkrash/zapisflow/blob/main/app/web/app.py): `app/web/app.py`
- [Tenant bot registry](https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/bot_registry.py): `app/services/bot_registry.py`
- [Shared bot dispatcher](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/bot_instance.py): `app/bot/bot_instance.py`
- [Tenant context](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/middlewares/tenant_context.py): `app/bot/middlewares/tenant_context.py`

### Platform Management

- [Platform manager bot](https://github.com/raiyaxkrash/zapisflow/blob/main/app/manager_bot/handlers.py): `app/manager_bot/handlers.py`
- [Bot provisioning](https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/bot_provisioning_service.py): `app/services/bot_provisioning_service.py`
- [Token encryption](https://github.com/raiyaxkrash/zapisflow/blob/main/app/core/token_crypto.py): `app/core/token_crypto.py`
- [Subscription lifecycle](https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/subscription_service.py): `app/services/subscription_service.py`

### Client Booking

- [Client booking flows](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/client/booking.py): `app/bot/handlers/client/booking.py`
- [Service catalog](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/client/services.py): `app/bot/handlers/client/services.py`
- [Availability calculation](https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/slot_engine.py): `app/services/slot_engine.py`
- [Booking lifecycle](https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/booking_service.py): `app/services/booking_service.py`
- [Client deposit flow](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/client/payment.py): `app/bot/handlers/client/payment.py`
- [Appointments and portfolio](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/client/my_appointments.py): `app/bot/handlers/client/my_appointments.py`

### Studio Management

- [Master admin CRM](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/admin/appointments.py): `app/bot/handlers/admin/appointments.py`
- [Schedule management](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/admin/calendar_mgmt.py): `app/bot/handlers/admin/calendar_mgmt.py`
- [Payment review](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/admin/payments.py): `app/bot/handlers/admin/payments.py`
- [Business analytics](https://github.com/raiyaxkrash/zapisflow/blob/main/app/bot/handlers/admin/analytics.py): `app/bot/handlers/admin/analytics.py`
- [Client broadcasts](https://github.com/raiyaxkrash/zapisflow/blob/main/app/services/broadcast_service.py): `app/services/broadcast_service.py`

### Persistence and Jobs

- [Scheduled jobs](https://github.com/raiyaxkrash/zapisflow/blob/main/app/scheduler/scheduler.py): `app/scheduler/scheduler.py`
- [Booking reminders](https://github.com/raiyaxkrash/zapisflow/blob/main/app/scheduler/jobs/reminder_worker.py): `app/scheduler/jobs/reminder_worker.py`
- [Data repositories](https://github.com/raiyaxkrash/zapisflow/blob/main/app/repositories/appointment_repository.py): `app/repositories/appointment_repository.py`
- [PostgreSQL data](https://github.com/raiyaxkrash/zapisflow/blob/main/app/database/session.py): `app/database/session.py`
- **Redis services**

### Other components

- **Telegram users**
- **Telegram API**

## Connections

- Telegram users → Webhook ingestion: sends updates
- Webhook ingestion → Tenant bot registry: resolves tenant bot (evidence: `app/web/app.py`)
- Webhook ingestion → Platform manager bot: routes manager updates
- Tenant bot registry → Shared bot dispatcher: provides bot
- Shared bot dispatcher → Tenant context: establishes tenant
- Tenant context → Client booking flows: routes client updates
- Tenant context → Master admin CRM: routes admin updates
- Platform manager bot → Bot provisioning: provisions bots (evidence: `app/manager_bot/handlers.py`)
- Bot provisioning → Token encryption: protects bot tokens (evidence: `app/services/bot_provisioning_service.py`)
- Platform manager bot → Subscription lifecycle: manages subscriptions (evidence: `app/manager_bot/handlers.py`)
- Client booking flows → Service catalog: browses services
- Client booking flows → Availability calculation: requests availability
- Client booking flows → Booking lifecycle: creates booking
- Booking lifecycle → Data repositories: persists booking
- Client booking flows → Client deposit flow: continues to deposit
- Client booking flows → Appointments and portfolio: views appointments
- Master admin CRM → Schedule management: manages schedule
- Master admin CRM → Payment review: reviews deposits
- Master admin CRM → Business analytics: reviews performance
- Master admin CRM → Client broadcasts: sends broadcasts
- Scheduled jobs → Booking reminders: runs reminder jobs (evidence: `app/scheduler/jobs/reminder_worker.py`)
- Booking reminders → Data repositories: loads booking data (evidence: `app/scheduler/jobs/reminder_worker.py`)
- Scheduled jobs → PostgreSQL data: uses database
- Scheduled jobs → Redis services: coordinates jobs
- Data repositories → PostgreSQL data: reads and writes
- Webhook ingestion → Redis services: deduplicates updates (evidence: `app/web/app.py`)
- Tenant bot registry → PostgreSQL data: loads bot records (evidence: `app/services/bot_registry.py`)
- Tenant bot registry → Telegram API: uses bot sessions
