# eliasasa/whatsapp-barber-booking architecture

> Architecture diagram of the GitHub repository eliasasa/whatsapp-barber-booking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eliasasa/whatsapp-barber-booking
- Repository: https://github.com/eliasasa/whatsapp-barber-booking

## Overview

WhatsApp Barber Booking is a barbershop appointment backend with two main entry points: customers message the bot to browse services, check availability, and book or cancel; administrators use authenticated APIs to manage appointments, clients, availability, services, bot controls, and WAHA sessions. The webhook processor filters incoming messages and dispatches conversation handling; the admin API routes operations to authentication and domain services. The README documents additional admin capabilities whose route internals were not sampled, so those are represented at the routes-directory level.

Main entry points: [`src/lib/prisma.ts`](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/lib/prisma.ts) (PostgreSQL data access), [`src/app.ts`](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/app.ts) (HTTP application), [`src/whatsapp/processWebhook.ts`](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/processWebhook.ts) (Webhook processor), [`src/routes`](https://github.com/eliasasa/whatsapp-barber-booking/tree/main/src/routes) (Admin API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_app["HTTP application<br/>[app.ts]"]
  node_webhookroute["Webhook endpoint<br/>[webhook.ts]"]
  node_processor["Webhook processor<br/>[processWebhook.ts]"]
end

subgraph group_conversation["WhatsApp conversations"]
  node_handler["Conversation handler<br/>[handler.ts]"]
  node_conversationstore["Conversation state"]
  node_flows["Bot conversation flows"]
  node_availabilityflow["Availability flow"]
  node_servicesflow["Services flow<br/>[servicesFlow.ts]"]
end

subgraph group_admin["Admin operations"]
  node_adminroutes["Admin API routes"]
  node_authroutes["Authentication routes<br/>[auth.ts]"]
  node_authmiddleware["Admin authentication"]
  node_authservice["Admin identity service<br/>[authService.ts]"]
  node_limiter["Login rate limiter"]
  node_clientroutes["Client management routes<br/>[clients.ts]"]
  node_broadcastservice["Broadcast service"]
  node_botstate["Bot state service<br/>[botStateService.ts]"]
  node_botmessages["Bot message service"]
end

subgraph group_domain["Booking domain"]
  node_clientservice["Client service<br/>[clientService.ts]"]
  node_bookingservices["Appointment services"]
  node_availabilityservice["Available slots service"]
  node_catalogservices["Service catalog"]
end

subgraph group_infra["Persistence and integrations"]
  node_prisma[("PostgreSQL data access<br/>[prisma.ts]")]
  node_wahaout["WhatsApp client<br/>[wahaClient.ts]"]
  node_wahaadmin["WAHA admin client<br/>[wahaAdminClient.ts]"]
end

node_customer(("WhatsApp customer"))
node_adminuser(("Admin user"))
node_waha["WAHA"]

node_adminuser -.->|"calls API"| node_app
node_customer -.->|"sends messages"| node_waha
node_waha -.->|"posts events"| node_webhookroute
node_app -->|"mounts routes"| node_adminroutes
node_app -->|"mounts routes"| node_authroutes
node_app -->|"mounts routes"| node_clientroutes
node_app -->|"mounts route"| node_webhookroute
node_app -.->|"mounts broadcast route"| node_broadcastservice
node_authroutes -->|"delegates auth"| node_authservice
node_authroutes -->|"protects endpoints"| node_authmiddleware
node_authroutes -->|"limits login"| node_limiter
node_authmiddleware -->|"verifies admin"| node_authservice
node_authservice -->|"reads admin records"| node_prisma
node_adminroutes -.->|"protects operations"| node_authmiddleware
node_adminroutes -.->|"manages appointments"| node_bookingservices
node_adminroutes -.->|"queries slots"| node_availabilityservice
node_adminroutes -.->|"accesses records"| node_prisma
node_clientroutes -->|"delegates client work"| node_clientservice
node_clientservice -->|"reads and writes clients"| node_prisma
node_clientservice -->|"resolves chat IDs"| node_wahaout
node_webhookroute -->|"processes event"| node_processor
node_processor -->|"checks client block"| node_clientservice
node_processor -->|"checks pause state"| node_botstate
node_processor -->|"dispatches message"| node_handler
node_processor -->|"updates conversation"| node_conversationstore
node_processor -->|"sends replies"| node_wahaout
node_handler -->|"reads and updates state"| node_conversationstore
node_handler -->|"dispatches flows"| node_flows
node_availabilityflow -->|"updates flow state"| node_conversationstore
node_availabilityflow -->|"queries slots"| node_availabilityservice
node_servicesflow -->|"updates flow state"| node_conversationstore
node_servicesflow -->|"lists services"| node_catalogservices
node_bookingservices -.->|"persists appointments"| node_prisma
node_availabilityservice -->|"reads availability data"| node_prisma
node_catalogservices -.->|"reads catalog"| node_prisma
node_broadcastservice -->|"records broadcasts"| node_prisma
node_broadcastservice -->|"sends campaigns"| node_wahaout
node_wahaadmin -.->|"controls sessions"| node_waha
node_botmessages -.->|"reads message config"| node_prisma

click node_app "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/app.ts"
click node_webhookroute "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/routes/webhook.ts"
click node_adminroutes "https://github.com/eliasasa/whatsapp-barber-booking/tree/main/src/routes"
click node_authroutes "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/routes/auth.ts"
click node_authmiddleware "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/middleware/requireAdminAuth.ts"
click node_authservice "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/auth/authService.ts"
click node_limiter "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/middleware/loginRateLimiter.ts"
click node_clientroutes "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/routes/clients.ts"
click node_clientservice "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/clients/clientService.ts"
click node_broadcastservice "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/broadcast/broadcastService.ts"
click node_processor "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/processWebhook.ts"
click node_handler "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/core/handler.ts"
click node_conversationstore "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/conversation/conversationStore.ts"
click node_flows "https://github.com/eliasasa/whatsapp-barber-booking/tree/main/src/whatsapp/flows"
click node_availabilityflow "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/flows/availabilityFlow.ts"
click node_servicesflow "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/flows/servicesFlow.ts"
click node_bookingservices "https://github.com/eliasasa/whatsapp-barber-booking/tree/main/src/services/appointments"
click node_availabilityservice "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/availability/ListAvailableSlotsService.ts"
click node_catalogservices "https://github.com/eliasasa/whatsapp-barber-booking/tree/main/src/services/catalog"
click node_prisma "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/lib/prisma.ts"
click node_wahaout "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/wahaClient.ts"
click node_wahaadmin "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/wahaAdminClient.ts"
click node_botstate "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/botState/botStateService.ts"
click node_botmessages "https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/botMessages/botMessageService.ts"

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_app,node_webhookroute,node_processor,node_adminuser toneBlue
class node_handler,node_conversationstore,node_flows,node_availabilityflow,node_servicesflow toneAmber
class node_adminroutes,node_authroutes,node_authmiddleware,node_authservice,node_limiter,node_clientroutes,node_broadcastservice,node_botstate,node_botmessages toneMint
class node_clientservice,node_bookingservices,node_availabilityservice,node_catalogservices toneRose
class node_prisma,node_wahaout,node_wahaadmin,node_customer,node_waha toneIndigo
```

## Components

### Application entry

- [HTTP application](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/app.ts): `src/app.ts`
- [Webhook endpoint](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/routes/webhook.ts): `src/routes/webhook.ts`
- [Webhook processor](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/processWebhook.ts): `src/whatsapp/processWebhook.ts`

### WhatsApp conversations

- [Conversation handler](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/core/handler.ts): `src/whatsapp/core/handler.ts`
- [Conversation state](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/conversation/conversationStore.ts): `src/whatsapp/conversation/conversationStore.ts`
- [Bot conversation flows](https://github.com/eliasasa/whatsapp-barber-booking/tree/main/src/whatsapp/flows): `src/whatsapp/flows`
- [Availability flow](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/flows/availabilityFlow.ts): `src/whatsapp/flows/availabilityFlow.ts`
- [Services flow](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/flows/servicesFlow.ts): `src/whatsapp/flows/servicesFlow.ts`

### Admin operations

- [Admin API routes](https://github.com/eliasasa/whatsapp-barber-booking/tree/main/src/routes): `src/routes`
- [Authentication routes](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/routes/auth.ts): `src/routes/auth.ts`
- [Admin authentication](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/middleware/requireAdminAuth.ts): `src/middleware/requireAdminAuth.ts`
- [Admin identity service](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/auth/authService.ts): `src/services/auth/authService.ts`
- [Login rate limiter](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/middleware/loginRateLimiter.ts): `src/middleware/loginRateLimiter.ts`
- [Client management routes](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/routes/clients.ts): `src/routes/clients.ts`
- [Broadcast service](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/broadcast/broadcastService.ts): `src/services/broadcast/broadcastService.ts`
- [Bot state service](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/botState/botStateService.ts): `src/services/botState/botStateService.ts`
- [Bot message service](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/botMessages/botMessageService.ts): `src/services/botMessages/botMessageService.ts`

### Booking domain

- [Client service](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/clients/clientService.ts): `src/services/clients/clientService.ts`
- [Appointment services](https://github.com/eliasasa/whatsapp-barber-booking/tree/main/src/services/appointments): `src/services/appointments`
- [Available slots service](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/services/availability/ListAvailableSlotsService.ts): `src/services/availability/ListAvailableSlotsService.ts`
- [Service catalog](https://github.com/eliasasa/whatsapp-barber-booking/tree/main/src/services/catalog): `src/services/catalog`

### Persistence and integrations

- [PostgreSQL data access](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`
- [WhatsApp client](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/wahaClient.ts): `src/whatsapp/wahaClient.ts`
- [WAHA admin client](https://github.com/eliasasa/whatsapp-barber-booking/blob/main/src/whatsapp/wahaAdminClient.ts): `src/whatsapp/wahaAdminClient.ts`

### Other components

- **WhatsApp customer**
- **Admin user**
- **WAHA**

## Connections

- Admin user → HTTP application: calls API (evidence: `README.md`)
- WhatsApp customer → WAHA: sends messages (evidence: `README.md`)
- WAHA → Webhook endpoint: posts events (evidence: `README.md`)
- HTTP application → Admin API routes: mounts routes (evidence: `src/app.ts`)
- HTTP application → Authentication routes: mounts routes (evidence: `src/app.ts`)
- HTTP application → Client management routes: mounts routes (evidence: `src/app.ts`)
- HTTP application → Webhook endpoint: mounts route (evidence: `src/app.ts`)
- HTTP application → Broadcast service: mounts broadcast route (evidence: `src/app.ts`)
- Authentication routes → Admin identity service: delegates auth (evidence: `src/routes/auth.ts`)
- Authentication routes → Admin authentication: protects endpoints (evidence: `src/routes/auth.ts`)
- Authentication routes → Login rate limiter: limits login (evidence: `src/routes/auth.ts`)
- Admin authentication → Admin identity service: verifies admin (evidence: `src/middleware/requireAdminAuth.ts`)
- Admin identity service → PostgreSQL data access: reads admin records (evidence: `src/services/auth/authService.ts`)
- Admin API routes → Admin authentication: protects operations (evidence: `README.md`)
- Admin API routes → Appointment services: manages appointments (evidence: `README.md`)
- Admin API routes → Available slots service: queries slots (evidence: `README.md`)
- Admin API routes → PostgreSQL data access: accesses records (evidence: `src/routes/services.ts`)
- Client management routes → Client service: delegates client work (evidence: `src/routes/clients.ts`)
- Client service → PostgreSQL data access: reads and writes clients (evidence: `src/services/clients/clientService.ts`)
- Client service → WhatsApp client: resolves chat IDs (evidence: `src/services/clients/clientService.ts`)
- Webhook endpoint → Webhook processor: processes event (evidence: `src/routes/webhook.ts`)
- Webhook processor → Client service: checks client block (evidence: `src/whatsapp/processWebhook.ts`)
- Webhook processor → Bot state service: checks pause state (evidence: `src/whatsapp/processWebhook.ts`)
- Webhook processor → Conversation handler: dispatches message (evidence: `src/whatsapp/processWebhook.ts`)
- Webhook processor → Conversation state: updates conversation (evidence: `src/whatsapp/processWebhook.ts`)
- Webhook processor → WhatsApp client: sends replies (evidence: `src/whatsapp/processWebhook.ts`)
- Conversation handler → Conversation state: reads and updates state (evidence: `src/whatsapp/core/handler.ts`)
- Conversation handler → Bot conversation flows: dispatches flows (evidence: `src/whatsapp/core/handler.ts`)
- Availability flow → Conversation state: updates flow state (evidence: `src/whatsapp/flows/availabilityFlow.ts`)
- Availability flow → Available slots service: queries slots (evidence: `src/whatsapp/flows/availabilityFlow.ts`)
- Services flow → Conversation state: updates flow state (evidence: `src/whatsapp/flows/servicesFlow.ts`)
- Services flow → Service catalog: lists services (evidence: `src/whatsapp/flows/servicesFlow.ts`)
- Appointment services → PostgreSQL data access: persists appointments (evidence: `src/services/appointments/createAppointmentService.ts`)
- Available slots service → PostgreSQL data access: reads availability data (evidence: `src/services/availability/ListAvailableSlotsService.ts`)
- Service catalog → PostgreSQL data access: reads catalog (evidence: `src/services/catalog/ListServicesService.ts`)
- Broadcast service → PostgreSQL data access: records broadcasts (evidence: `src/services/broadcast/broadcastService.ts`)
- Broadcast service → WhatsApp client: sends campaigns (evidence: `src/services/broadcast/broadcastService.ts`)
- WAHA admin client → WAHA: controls sessions (evidence: `README.md`)
- Bot message service → PostgreSQL data access: reads message config (evidence: `src/services/botMessages/botMessageService.ts`)