# r3mem1/lidpilot architecture

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

- Interactive diagram: https://gitdiagram.com/r3mem1/lidpilot
- Repository: https://github.com/r3mem1/lidpilot

## Overview

LeadPilot is a multi-tenant business inbox and CRM: customer messages arrive through Telegram or VK, are stored and processed by an AI pipeline, then answered or escalated into manager workflows and leads. A second major workflow handles staff schedules and bookings, including AI-assisted booking requests and staff notifications. The README documents the major capabilities; source excerpts and the SOURCE INDEX support the depicted calls. Several route and subsystem implementations were not sampled, so their internal links are omitted where ownership is uncertain.

Main entry points: [`main.py`](https://github.com/r3mem1/lidpilot/blob/main/main.py) (FastAPI app), [`services/message_service.py`](https://github.com/r3mem1/lidpilot/blob/main/services/message_service.py) (Message processing), [`routes/messages.py`](https://github.com/r3mem1/lidpilot/blob/main/routes/messages.py) (Message webhooks), [`services/booking_service.py`](https://github.com/r3mem1/lidpilot/blob/main/services/booking_service.py) (Booking service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application access"]
  node_main["FastAPI app<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_business_routes["Business API<br/>[businesses.py]"]
  node_cabinet_routes["Business cabinet<br/>[cabinet.py]"]
  node_admin_routes["Admin panel<br/>[admin.py]"]
end

subgraph group_messaging["Messaging and CRM"]
  node_messages_routes["Message webhooks<br/>[messages.py]"]
  node_channels["Channel clients<br/>[base.py]"]
  node_telegram["Telegram adapter<br/>[telegram.py]"]
  node_vk["VK adapter<br/>[vk.py]"]
  node_message_service["Message processing<br/>[message_service.py]"]
  node_crm["Leads and customers<br/>[lead_service.py]"]
end

subgraph group_ai["AI processing"]
  node_ai_pipeline["AI pipeline<br/>[pipeline.py]"]
  node_ai_context["Business AI context<br/>[context.py]"]
end

subgraph group_booking["Staff booking"]
  node_booking_engine["AI booking engine<br/>[booking.py]"]
  node_scheduling["Staff schedules"]
  node_booking_service["Booking service<br/>[booking_service.py]"]
  node_booking_routes["Booking routes<br/>[bookings.py]"]
  node_master_notify["Staff notifications"]
end

subgraph group_platform["Platform operations"]
  node_database[("Application database<br/>[models.py]")]
  node_access["Access control<br/>[access_service.py]"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
  node_integration_service["Integration setup"]
  node_audit["Audit log<br/>[audit_service.py]"]
  node_admin_service["Admin operations<br/>[admin_service.py]"]
end

node_customer(("Customer"))
node_business_staff(("Business staff"))

node_main -->|"mounts routes"| node_auth_routes
node_main -->|"mounts routes"| node_messages_routes
node_main -->|"mounts routes"| node_booking_routes
node_main -->|"mounts routes"| node_business_routes
node_main -->|"mounts routes"| node_cabinet_routes
node_main -->|"mounts routes"| node_admin_routes
node_customer -->|"sends messages"| node_messages_routes
node_messages_routes -->|"delegates processing"| node_message_service
node_messages_routes -->|"receives Telegram"| node_telegram
node_messages_routes -->|"receives VK"| node_vk
node_telegram -->|"implements contract"| node_channels
node_vk -->|"implements contract"| node_channels
node_message_service -->|"runs AI pipeline"| node_ai_pipeline
node_message_service -->|"registers classification"| node_crm
node_message_service -->|"stores messages"| node_database
node_ai_pipeline -->|"uses business facts"| node_ai_context
node_business_routes -->|"provides business context"| node_ai_context
node_business_staff -->|"manages inbox"| node_cabinet_routes
node_cabinet_routes -->|"views CRM"| node_crm
node_business_staff -->|"manages bookings"| node_booking_routes
node_booking_routes -->|"manages bookings"| node_booking_service
node_booking_routes -->|"manages shifts"| node_scheduling
node_message_service -->|"handles AI booking"| node_booking_engine
node_booking_engine -->|"checks booking slots"| node_booking_service
node_booking_service -->|"uses staff shifts"| node_scheduling
node_booking_service -->|"persists bookings"| node_database
node_booking_service -.->|"notifies staff"| node_master_notify
node_integration_service -->|"configures Telegram"| node_telegram
node_integration_service -->|"configures VK"| node_vk
node_message_service -->|"uses channel contract"| node_channels
node_auth_routes -->|"authenticates users"| node_auth_service
node_auth_routes -->|"checks access"| node_access
node_access -->|"reads memberships"| node_database
node_auth_service -->|"loads users"| node_database
node_admin_routes -->|"delegates admin work"| node_admin_service
node_admin_service -->|"records changes"| node_audit
node_audit -->|"writes system logs"| node_database

click node_main "https://github.com/r3mem1/lidpilot/blob/main/main.py"
click node_auth_routes "https://github.com/r3mem1/lidpilot/blob/main/routes/auth.py"
click node_business_routes "https://github.com/r3mem1/lidpilot/blob/main/routes/businesses.py"
click node_cabinet_routes "https://github.com/r3mem1/lidpilot/blob/main/routes/cabinet.py"
click node_admin_routes "https://github.com/r3mem1/lidpilot/blob/main/routes/admin.py"
click node_messages_routes "https://github.com/r3mem1/lidpilot/blob/main/routes/messages.py"
click node_channels "https://github.com/r3mem1/lidpilot/blob/main/integrations/base.py"
click node_telegram "https://github.com/r3mem1/lidpilot/blob/main/integrations/telegram.py"
click node_vk "https://github.com/r3mem1/lidpilot/blob/main/integrations/vk.py"
click node_message_service "https://github.com/r3mem1/lidpilot/blob/main/services/message_service.py"
click node_crm "https://github.com/r3mem1/lidpilot/blob/main/services/lead_service.py"
click node_ai_pipeline "https://github.com/r3mem1/lidpilot/blob/main/ai/pipeline.py"
click node_ai_context "https://github.com/r3mem1/lidpilot/blob/main/ai/context.py"
click node_booking_engine "https://github.com/r3mem1/lidpilot/blob/main/ai/booking.py"
click node_scheduling "https://github.com/r3mem1/lidpilot/blob/main/services/schedule_service.py"
click node_booking_service "https://github.com/r3mem1/lidpilot/blob/main/services/booking_service.py"
click node_booking_routes "https://github.com/r3mem1/lidpilot/blob/main/routes/bookings.py"
click node_master_notify "https://github.com/r3mem1/lidpilot/blob/main/services/master_notify_service.py"
click node_database "https://github.com/r3mem1/lidpilot/blob/main/models.py"
click node_access "https://github.com/r3mem1/lidpilot/blob/main/services/access_service.py"
click node_auth_service "https://github.com/r3mem1/lidpilot/blob/main/services/auth_service.py"
click node_integration_service "https://github.com/r3mem1/lidpilot/blob/main/services/integration_service.py"
click node_audit "https://github.com/r3mem1/lidpilot/blob/main/services/audit_service.py"
click node_admin_service "https://github.com/r3mem1/lidpilot/blob/main/services/admin_service.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_main,node_auth_routes,node_business_routes,node_cabinet_routes,node_admin_routes toneBlue
class node_messages_routes,node_channels,node_telegram,node_vk,node_message_service,node_crm toneAmber
class node_ai_pipeline,node_ai_context toneMint
class node_booking_engine,node_scheduling,node_booking_service,node_booking_routes,node_master_notify toneRose
class node_database,node_access,node_auth_service,node_integration_service,node_audit,node_admin_service,node_customer,node_business_staff toneIndigo
```

## Components

### Application access

- [FastAPI app](https://github.com/r3mem1/lidpilot/blob/main/main.py): `main.py`
- [Auth routes](https://github.com/r3mem1/lidpilot/blob/main/routes/auth.py): `routes/auth.py`
- [Business API](https://github.com/r3mem1/lidpilot/blob/main/routes/businesses.py): `routes/businesses.py`
- [Business cabinet](https://github.com/r3mem1/lidpilot/blob/main/routes/cabinet.py): `routes/cabinet.py`
- [Admin panel](https://github.com/r3mem1/lidpilot/blob/main/routes/admin.py): `routes/admin.py`

### Messaging and CRM

- [Message webhooks](https://github.com/r3mem1/lidpilot/blob/main/routes/messages.py): `routes/messages.py`
- [Channel clients](https://github.com/r3mem1/lidpilot/blob/main/integrations/base.py): `integrations/base.py`
- [Telegram adapter](https://github.com/r3mem1/lidpilot/blob/main/integrations/telegram.py): `integrations/telegram.py`
- [VK adapter](https://github.com/r3mem1/lidpilot/blob/main/integrations/vk.py): `integrations/vk.py`
- [Message processing](https://github.com/r3mem1/lidpilot/blob/main/services/message_service.py): `services/message_service.py`
- [Leads and customers](https://github.com/r3mem1/lidpilot/blob/main/services/lead_service.py): `services/lead_service.py`

### AI processing

- [AI pipeline](https://github.com/r3mem1/lidpilot/blob/main/ai/pipeline.py): `ai/pipeline.py`
- [Business AI context](https://github.com/r3mem1/lidpilot/blob/main/ai/context.py): `ai/context.py`

### Staff booking

- [AI booking engine](https://github.com/r3mem1/lidpilot/blob/main/ai/booking.py): `ai/booking.py`
- [Staff schedules](https://github.com/r3mem1/lidpilot/blob/main/services/schedule_service.py): `services/schedule_service.py`
- [Booking service](https://github.com/r3mem1/lidpilot/blob/main/services/booking_service.py): `services/booking_service.py`
- [Booking routes](https://github.com/r3mem1/lidpilot/blob/main/routes/bookings.py): `routes/bookings.py`
- [Staff notifications](https://github.com/r3mem1/lidpilot/blob/main/services/master_notify_service.py): `services/master_notify_service.py`

### Platform operations

- [Application database](https://github.com/r3mem1/lidpilot/blob/main/models.py): `models.py`
- [Access control](https://github.com/r3mem1/lidpilot/blob/main/services/access_service.py): `services/access_service.py`
- [Authentication](https://github.com/r3mem1/lidpilot/blob/main/services/auth_service.py): `services/auth_service.py`
- [Integration setup](https://github.com/r3mem1/lidpilot/blob/main/services/integration_service.py): `services/integration_service.py`
- [Audit log](https://github.com/r3mem1/lidpilot/blob/main/services/audit_service.py): `services/audit_service.py`
- [Admin operations](https://github.com/r3mem1/lidpilot/blob/main/services/admin_service.py): `services/admin_service.py`

### Other components

- **Customer**
- **Business staff**

## Connections

- FastAPI app → Auth routes: mounts routes (evidence: `main.py`)
- FastAPI app → Message webhooks: mounts routes (evidence: `main.py`)
- FastAPI app → Booking routes: mounts routes (evidence: `main.py`)
- FastAPI app → Business API: mounts routes (evidence: `main.py`)
- FastAPI app → Business cabinet: mounts routes (evidence: `main.py`)
- FastAPI app → Admin panel: mounts routes (evidence: `main.py`)
- Customer → Message webhooks: sends messages
- Message webhooks → Message processing: delegates processing (evidence: `routes/messages.py`)
- Message webhooks → Telegram adapter: receives Telegram (evidence: `routes/messages.py`)
- Message webhooks → VK adapter: receives VK (evidence: `routes/messages.py`)
- Telegram adapter → Channel clients: implements contract (evidence: `integrations/telegram.py`)
- VK adapter → Channel clients: implements contract (evidence: `integrations/vk.py`)
- Message processing → AI pipeline: runs AI pipeline (evidence: `services/message_service.py`)
- Message processing → Leads and customers: registers classification (evidence: `services/message_service.py`)
- Message processing → Application database: stores messages (evidence: `services/message_service.py`)
- AI pipeline → Business AI context: uses business facts (evidence: `ai/pipeline.py`)
- Business API → Business AI context: provides business context (evidence: `routes/businesses.py`)
- Business staff → Business cabinet: manages inbox
- Business cabinet → Leads and customers: views CRM (evidence: `routes/cabinet.py`)
- Business staff → Booking routes: manages bookings
- Booking routes → Booking service: manages bookings (evidence: `routes/bookings.py`)
- Booking routes → Staff schedules: manages shifts (evidence: `routes/bookings.py`)
- Message processing → AI booking engine: handles AI booking (evidence: `services/message_service.py`)
- AI booking engine → Booking service: checks booking slots
- Booking service → Staff schedules: uses staff shifts (evidence: `services/booking_service.py`)
- Booking service → Application database: persists bookings (evidence: `services/booking_service.py`)
- Booking service → Staff notifications: notifies staff (evidence: `services/master_notify_service.py`)
- Integration setup → Telegram adapter: configures Telegram (evidence: `services/integration_service.py`)
- Integration setup → VK adapter: configures VK (evidence: `services/integration_service.py`)
- Message processing → Channel clients: uses channel contract (evidence: `services/message_service.py`)
- Auth routes → Authentication: authenticates users (evidence: `routes/auth.py`)
- Auth routes → Access control: checks access (evidence: `routes/auth.py`)
- Access control → Application database: reads memberships (evidence: `services/access_service.py`)
- Authentication → Application database: loads users (evidence: `services/auth_service.py`)
- Admin panel → Admin operations: delegates admin work
- Admin operations → Audit log: records changes (evidence: `services/admin_service.py`)
- Audit log → Application database: writes system logs (evidence: `services/audit_service.py`)
