# bibinprathap/whatsapp-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/bibinprathap/whatsapp-chatbot
- Repository: https://github.com/bibinprathap/whatsapp-chatbot

## Overview

This is a WhatsApp sales and ordering bot. A customer message enters through the WhatsApp connection, is checked for a natural-language order, and either becomes a validated cart or falls through to the numbered stage flow; both paths persist customer state and send replies. The product also supports attendant handoff and scheduled abandoned-cart recovery. The sampled code shows the message handler, NLP path, selected stages, storage helpers, and recovery job; connections among unsampled stage implementations are therefore shown only where documented by the README or registry.

Main entry points: [`src/stages.js`](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages.js) (Stage router), [`src/server.js`](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/server.js) (Message server), [`src/nlp/index.js`](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/nlp/index.js) (Natural-language processor), [`src/storage.js`](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/storage.js) (State access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation handling"]
  node_server["Message server<br/>[server.js]"]
  node_stage_registry["Stage router<br/>[stages.js]"]
end

subgraph group_ordering["Order flows"]
  node_welcome["Welcome stage<br/>[0.js]"]
  node_menu_stage["Menu stage<br/>[1.js]"]
  node_cart_stage["Cart stage<br/>[2.js]"]
  node_address_stage["Address and bill<br/>[3.js]"]
  node_confirmation_stage["Order stage<br/>[4.js]"]
  node_attendant_stage["Attendant handoff<br/>[5.js]"]
  node_recovery_stage["Recovery stage<br/>[99.js]"]
  node_nl_processor["Natural-language processor<br/>[index.js]"]
  node_nl_prefilter["Order pre-filter<br/>[parser.js]"]
  node_cart_builder["Cart and summary builder<br/>[parser.js]"]
  node_catalog["Product catalog<br/>[menu.js]"]
end

subgraph group_state["State and recovery"]
  node_storage["State access<br/>[storage.js]"]
  node_database[("SQLite state store<br/>[db.js]")]
  node_recovery_job["Abandoned-cart job<br/>[cron_jobs.js]"]
end

subgraph group_integrations["External integrations"]
  node_openai_parser["OpenAI order parser<br/>[openai.js]"]
  node_whatsapp{{"WhatsApp service"}}
  node_openai_service{{"OpenAI service"}}
end

node_customer(("Customer"))

node_customer -->|"sends message"| node_whatsapp
node_whatsapp -->|"delivers message"| node_server
node_server -->|"sends replies"| node_whatsapp
node_server -->|"loads state"| node_storage
node_server -->|"checks order"| node_nl_processor
node_nl_processor -->|"filters message"| node_nl_prefilter
node_nl_processor -.->|"parses order"| node_openai_parser
node_openai_parser -.->|"calls model"| node_openai_service
node_openai_parser -->|"reads menu"| node_catalog
node_nl_processor -->|"builds cart"| node_cart_builder
node_cart_builder -->|"validates items"| node_catalog
node_nl_processor -->|"saves order state"| node_storage
node_nl_processor -->|"sends summary"| node_whatsapp
node_server -->|"falls back to"| node_stage_registry
node_stage_registry -->|"dispatches stage"| node_welcome
node_stage_registry -->|"dispatches stage"| node_menu_stage
node_stage_registry -->|"dispatches stage"| node_cart_stage
node_stage_registry -->|"dispatches stage"| node_address_stage
node_stage_registry -->|"dispatches stage"| node_confirmation_stage
node_stage_registry -->|"dispatches stage"| node_attendant_stage
node_stage_registry -->|"dispatches stage"| node_recovery_stage
node_menu_stage -->|"reads menu"| node_catalog
node_menu_stage -->|"saves stage"| node_storage
node_address_stage -->|"saves address"| node_storage
node_server -->|"starts job"| node_recovery_job
node_recovery_job -->|"queries stale carts"| node_database
node_recovery_job -->|"loads and updates state"| node_storage
node_recovery_job -->|"sends nudges"| node_whatsapp
node_storage -->|"reads and writes"| node_database

click node_server "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/server.js"
click node_stage_registry "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages.js"
click node_welcome "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/0.js"
click node_menu_stage "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/1.js"
click node_cart_stage "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/2.js"
click node_address_stage "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/3.js"
click node_confirmation_stage "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/4.js"
click node_attendant_stage "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/5.js"
click node_recovery_stage "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/99.js"
click node_nl_processor "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/nlp/index.js"
click node_nl_prefilter "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/nlp/parser.js"
click node_openai_parser "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/nlp/openai.js"
click node_cart_builder "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/nlp/parser.js"
click node_catalog "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/menu.js"
click node_storage "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/storage.js"
click node_database "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/db.js"
click node_recovery_job "https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/cron_jobs.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_server,node_stage_registry toneBlue
class node_welcome,node_menu_stage,node_cart_stage,node_address_stage,node_confirmation_stage,node_attendant_stage,node_recovery_stage,node_nl_processor,node_nl_prefilter,node_cart_builder,node_catalog toneAmber
class node_storage,node_database,node_recovery_job toneMint
class node_openai_parser,node_whatsapp,node_openai_service toneRose
class node_customer toneIndigo
```

## Components

### Conversation handling

- [Message server](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/server.js): `src/server.js`
- [Stage router](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages.js): `src/stages.js`

### Order flows

- [Welcome stage](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/0.js): `src/stages/0.js`
- [Menu stage](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/1.js): `src/stages/1.js`
- [Cart stage](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/2.js): `src/stages/2.js`
- [Address and bill](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/3.js): `src/stages/3.js`
- [Order stage](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/4.js): `src/stages/4.js`
- [Attendant handoff](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/5.js): `src/stages/5.js`
- [Recovery stage](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/stages/99.js): `src/stages/99.js`
- [Natural-language processor](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/nlp/index.js): `src/nlp/index.js`
- [Order pre-filter](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/nlp/parser.js): `src/nlp/parser.js`
- [Cart and summary builder](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/nlp/parser.js): `src/nlp/parser.js`
- [Product catalog](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/menu.js): `src/menu.js`

### State and recovery

- [State access](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/storage.js): `src/storage.js`
- [SQLite state store](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/db.js): `src/db.js`
- [Abandoned-cart job](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/cron_jobs.js): `src/cron_jobs.js`

### External integrations

- [OpenAI order parser](https://github.com/bibinprathap/whatsapp-chatbot/blob/master/src/nlp/openai.js): `src/nlp/openai.js`
- **WhatsApp service**
- **OpenAI service**

### Other components

- **Customer**

## Connections

- Customer → WhatsApp service: sends message
- WhatsApp service → Message server: delivers message
- Message server → WhatsApp service: sends replies
- Message server → State access: loads state
- Message server → Natural-language processor: checks order
- Natural-language processor → Order pre-filter: filters message
- Natural-language processor → OpenAI order parser: parses order
- OpenAI order parser → OpenAI service: calls model
- OpenAI order parser → Product catalog: reads menu
- Natural-language processor → Cart and summary builder: builds cart
- Cart and summary builder → Product catalog: validates items
- Natural-language processor → State access: saves order state
- Natural-language processor → WhatsApp service: sends summary
- Message server → Stage router: falls back to
- Stage router → Welcome stage: dispatches stage
- Stage router → Menu stage: dispatches stage
- Stage router → Cart stage: dispatches stage
- Stage router → Address and bill: dispatches stage
- Stage router → Order stage: dispatches stage
- Stage router → Attendant handoff: dispatches stage
- Stage router → Recovery stage: dispatches stage
- Menu stage → Product catalog: reads menu
- Menu stage → State access: saves stage
- Address and bill → State access: saves address
- Message server → Abandoned-cart job: starts job
- Abandoned-cart job → SQLite state store: queries stale carts
- Abandoned-cart job → State access: loads and updates state
- Abandoned-cart job → WhatsApp service: sends nudges
- State access → SQLite state store: reads and writes