# nasserelbacha2002/tea-bot architecture

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

- Interactive diagram: https://gitdiagram.com/nasserelbacha2002/tea-bot
- Repository: https://github.com/nasserelbacha2002/tea-bot

## Overview

Tea-bot pairs a React admin/editor with an Express WhatsApp automation backend. The main runtime path receives a provider webhook, processes an inbound turn through the flow engine and session state, then persists and sends a response; administrators manage and publish flows through the frontend and API. The README documents Meta and Twilio webhooks, draft/published flows, simulation, monitoring, and conversation inbox features. Some backend routes and frontend API wiring were not sampled, so those links are included only where documented; other edges follow the excerpts or SOURCE INDEX references.

Main entry points: [`frontend/src/app/router.tsx`](https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/app/router.tsx) (App routes), [`whatsapp-bot/src/services/twilio-inbound-pipeline.js`](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/twilio-inbound-pipeline.js) (Inbound turn pipeline), [`whatsapp-bot/src/utils/flow-loader.js`](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/utils/flow-loader.js) (Flow loading), [`whatsapp-bot/src/controllers/twilio-webhook.controller.js`](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/controllers/twilio-webhook.controller.js) (Inbound webhook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Admin frontend"]
  node_router["App routes<br/>[router.tsx]"]
  node_login["Authentication UI<br/>[LoginPage.tsx]"]
  node_inboxui["Conversation inbox"]
  node_monitorui["Monitoring UI<br/>[MonitoringPage.tsx]"]
end

subgraph group_flows["Flow authoring"]
  node_flowui["Flow editor"]
  node_flowmanageui["Flow administration"]
  node_flowsapi["Flow management API"]
  node_simulator["Flow simulator"]
end

subgraph group_runtime["Messaging runtime"]
  node_authapi["Auth API<br/>[auth.controller.js]"]
  node_inbound["Inbound webhook"]
  node_pipeline["Inbound turn pipeline"]
  node_engine["Flow engine"]
  node_loader["Flow loading<br/>[flow-loader.js]"]
  node_compiler["Flow compilation<br/>[compile-flow.js]"]
  node_handoff["Human handoff"]
  node_outbound["Provider delivery"]
end

subgraph group_inbox["Inbox and monitoring"]
  node_conversationapi["Conversation API"]
  node_monitoring["Monitoring services"]
end

subgraph group_storage["Persistence"]
  node_sessions["Session state<br/>[session.service.js]"]
  node_flowrepo[("Flow repository")]
  node_convosessions[("Conversation sessions")]
  node_db[("SQL Server<br/>[index.js]")]
end

node_admin(("Admin user"))
node_customer(("WhatsApp user"))
node_provider{{"WhatsApp providers"}}

node_admin -->|"uses panel"| node_router
node_router -->|"routes to"| node_login
node_router -->|"routes to"| node_inboxui
node_router -->|"routes to"| node_monitorui
node_router -->|"routes to"| node_flowui
node_router -.->|"routes to"| node_flowmanageui
node_login -.->|"authenticates via"| node_authapi
node_flowui -.->|"manages flows via"| node_flowsapi
node_flowmanageui -.->|"manages flows via"| node_flowsapi
node_inboxui -.->|"loads conversations via"| node_conversationapi
node_monitorui -.->|"views monitoring via"| node_monitoring
node_customer -->|"sends message"| node_provider
node_provider -->|"posts webhook"| node_inbound
node_inbound -->|"dispatches turn"| node_pipeline
node_pipeline -->|"resolves message"| node_engine
node_pipeline -->|"uses session state"| node_sessions
node_engine -->|"loads flows"| node_loader
node_loader -->|"loads published flows"| node_flowrepo
node_loader -->|"compiles flow"| node_compiler
node_pipeline -->|"checks handoff"| node_handoff
node_pipeline -.->|"delivers response"| node_outbound
node_provider -.->|"posts Meta webhook"| node_inbound
node_flowrepo -.->|"stores flow data"| node_db
node_convosessions -->|"queries and writes"| node_db

click node_router "https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/app/router.tsx"
click node_login "https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/auth/pages/LoginPage.tsx"
click node_inboxui "https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/conversations/pages/ConversationsPage.tsx"
click node_monitorui "https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/monitoring/pages/MonitoringPage.tsx"
click node_flowui "https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/flows/editor/ConversationEditorPage.tsx"
click node_flowmanageui "https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/flow-management/pages/FlowMgmtListPage.tsx"
click node_authapi "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/controllers/auth.controller.js"
click node_inbound "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/controllers/twilio-webhook.controller.js"
click node_pipeline "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/twilio-inbound-pipeline.js"
click node_engine "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/flow-engine.service.js"
click node_loader "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/utils/flow-loader.js"
click node_compiler "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/utils/compile-flow.js"
click node_handoff "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/human-handoff.service.js"
click node_outbound "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/twilio-message-delivery.service.js"
click node_flowsapi "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/controllers/flow-management.controller.js"
click node_simulator "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/simulator.service.js"
click node_conversationapi "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/controllers/conversations.controller.js"
click node_monitoring "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/monitoring/monitoring.service.js"
click node_sessions "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/session.service.js"
click node_flowrepo "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/repositories/flow-db.repository.js"
click node_convosessions "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/repositories/conversation-session.repository.js"
click node_db "https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/db/index.js"

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_router,node_login,node_inboxui,node_monitorui,node_admin,node_customer toneBlue
class node_flowui,node_flowmanageui,node_flowsapi,node_simulator toneAmber
class node_authapi,node_inbound,node_pipeline,node_engine,node_loader,node_compiler,node_handoff,node_outbound toneMint
class node_conversationapi,node_monitoring toneRose
class node_sessions,node_flowrepo,node_convosessions,node_db,node_provider toneIndigo
```

## Components

### Admin frontend

- [App routes](https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/app/router.tsx): `frontend/src/app/router.tsx`
- [Authentication UI](https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/auth/pages/LoginPage.tsx): `frontend/src/features/auth/pages/LoginPage.tsx`
- [Conversation inbox](https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/conversations/pages/ConversationsPage.tsx): `frontend/src/features/conversations/pages/ConversationsPage.tsx`
- [Monitoring UI](https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/monitoring/pages/MonitoringPage.tsx): `frontend/src/features/monitoring/pages/MonitoringPage.tsx`

### Flow authoring

- [Flow editor](https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/flows/editor/ConversationEditorPage.tsx): `frontend/src/features/flows/editor/ConversationEditorPage.tsx`
- [Flow administration](https://github.com/nasserelbacha2002/tea-bot/blob/main/frontend/src/features/flow-management/pages/FlowMgmtListPage.tsx): `frontend/src/features/flow-management/pages/FlowMgmtListPage.tsx`
- [Flow management API](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/controllers/flow-management.controller.js): `whatsapp-bot/src/controllers/flow-management.controller.js`
- [Flow simulator](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/simulator.service.js): `whatsapp-bot/src/services/simulator.service.js`

### Messaging runtime

- [Auth API](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/controllers/auth.controller.js): `whatsapp-bot/src/controllers/auth.controller.js`
- [Inbound webhook](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/controllers/twilio-webhook.controller.js): `whatsapp-bot/src/controllers/twilio-webhook.controller.js`
- [Inbound turn pipeline](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/twilio-inbound-pipeline.js): `whatsapp-bot/src/services/twilio-inbound-pipeline.js`
- [Flow engine](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/flow-engine.service.js): `whatsapp-bot/src/services/flow-engine.service.js`
- [Flow loading](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/utils/flow-loader.js): `whatsapp-bot/src/utils/flow-loader.js`
- [Flow compilation](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/utils/compile-flow.js): `whatsapp-bot/src/utils/compile-flow.js`
- [Human handoff](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/human-handoff.service.js): `whatsapp-bot/src/services/human-handoff.service.js`
- [Provider delivery](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/twilio-message-delivery.service.js): `whatsapp-bot/src/services/twilio-message-delivery.service.js`

### Inbox and monitoring

- [Conversation API](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/controllers/conversations.controller.js): `whatsapp-bot/src/controllers/conversations.controller.js`
- [Monitoring services](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/monitoring/monitoring.service.js): `whatsapp-bot/src/monitoring/monitoring.service.js`

### Persistence

- [Session state](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/services/session.service.js): `whatsapp-bot/src/services/session.service.js`
- [Flow repository](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/repositories/flow-db.repository.js): `whatsapp-bot/src/repositories/flow-db.repository.js`
- [Conversation sessions](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/repositories/conversation-session.repository.js): `whatsapp-bot/src/repositories/conversation-session.repository.js`
- [SQL Server](https://github.com/nasserelbacha2002/tea-bot/blob/main/whatsapp-bot/src/db/index.js): `whatsapp-bot/src/db/index.js`

### Other components

- **Admin user**
- **WhatsApp user**
- **WhatsApp providers**

## Connections

- Admin user → App routes: uses panel
- App routes → Authentication UI: routes to (evidence: `frontend/src/app/router.tsx`)
- App routes → Conversation inbox: routes to (evidence: `frontend/src/app/router.tsx`)
- App routes → Monitoring UI: routes to (evidence: `frontend/src/app/router.tsx`)
- App routes → Flow editor: routes to (evidence: `frontend/src/app/router.tsx`)
- App routes → Flow administration: routes to
- Authentication UI → Auth API: authenticates via
- Flow editor → Flow management API: manages flows via
- Flow administration → Flow management API: manages flows via
- Conversation inbox → Conversation API: loads conversations via
- Monitoring UI → Monitoring services: views monitoring via
- WhatsApp user → WhatsApp providers: sends message
- WhatsApp providers → Inbound webhook: posts webhook
- Inbound webhook → Inbound turn pipeline: dispatches turn (evidence: `whatsapp-bot/src/controllers/twilio-webhook.controller.js`)
- Inbound turn pipeline → Flow engine: resolves message (evidence: `whatsapp-bot/src/services/twilio-inbound-pipeline.js`)
- Inbound turn pipeline → Session state: uses session state (evidence: `whatsapp-bot/src/services/twilio-inbound-pipeline.js`)
- Flow engine → Flow loading: loads flows (evidence: `whatsapp-bot/src/services/flow-engine.service.js`)
- Flow loading → Flow repository: loads published flows (evidence: `whatsapp-bot/src/utils/flow-loader.js`)
- Flow loading → Flow compilation: compiles flow (evidence: `whatsapp-bot/src/utils/flow-loader.js`)
- Inbound turn pipeline → Human handoff: checks handoff (evidence: `whatsapp-bot/src/services/twilio-inbound-pipeline.js`)
- Inbound turn pipeline → Provider delivery: delivers response
- WhatsApp providers → Inbound webhook: posts Meta webhook
- Flow repository → SQL Server: stores flow data
- Conversation sessions → SQL Server: queries and writes (evidence: `whatsapp-bot/src/repositories/conversation-session.repository.js`)
