# unilights/whatsapp-bot architecture

> Architecture diagram of the GitHub repository unilights/whatsapp-bot, 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/unilights/whatsapp-bot
- Repository: https://github.com/unilights/whatsapp-bot

## Overview

This is a WhatsApp attendance bot: it reads messages from a configured group, classifies attendance notes, and records them in Google Sheets and optionally MongoDB. Its main workflow handles live messages; when WhatsApp becomes ready, the same orchestrator also starts historical backfill. A shared processed-ID file prevents duplicate handling. The API provides QR-linking/status endpoints and attendance analytics backed by MongoDB. The README documents the supported attendance types, employee sheets, and backfill; source excerpts show the runtime calls. Other subsystems are represented from README capabilities and the source index where their implementation was not sampled.

Main entry points: [`src/whatsapp.js`](https://github.com/unilights/whatsapp-bot/blob/main/src/whatsapp.js) (WhatsApp client), [`src/backfill.js`](https://github.com/unilights/whatsapp-bot/blob/main/src/backfill.js) (History backfill), [`src/api.js`](https://github.com/unilights/whatsapp-bot/blob/main/src/api.js) (HTTP API), [`src/sheets.js`](https://github.com/unilights/whatsapp-bot/blob/main/src/sheets.js) (Sheet writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Message ingestion"]
  node_main["Runtime startup<br/>[index.js]"]
  node_whatsapp["WhatsApp client<br/>[whatsapp.js]"]
  node_backfill["History backfill<br/>[backfill.js]"]
end

subgraph group_processing["Attendance processing"]
  node_parser["Message parser<br/>[parser.js]"]
  node_keywords["Type keywords<br/>[parser-config.js]"]
  node_dedupe[("Processed IDs<br/>[processed-ids.js]")]
  node_config["Runtime configuration<br/>[config.js]"]
end

subgraph group_storage["Attendance storage"]
  node_sheets["Sheet writer<br/>[sheets.js]"]
  node_attendance_store["Attendance store"]
  node_db["MongoDB connection<br/>[db.js]"]
end

subgraph group_access["Linking and analytics"]
  node_api["HTTP API<br/>[api.js]"]
  node_qr_state["QR connection state<br/>[qr-state.js]"]
  node_dashboard["Dashboard UI<br/>[index.html]"]
end

node_hr(("HR operator"))
node_whatsapp_service(("WhatsApp group"))
node_google_sheets[("Google Sheets")]
node_mongodb_service[("MongoDB")]

node_hr -->|"sends messages"| node_whatsapp
node_main -->|"connects"| node_db
node_main -->|"starts"| node_api
node_main -->|"starts"| node_whatsapp
node_whatsapp_service -->|"delivers events"| node_whatsapp
node_whatsapp -->|"parses messages"| node_parser
node_backfill -->|"fetches history"| node_whatsapp_service
node_whatsapp -->|"starts on ready"| node_backfill
node_backfill -->|"parses messages"| node_parser
node_parser -->|"matches types"| node_keywords
node_whatsapp -->|"checks and records IDs"| node_dedupe
node_backfill -->|"checks and records IDs"| node_dedupe
node_whatsapp -->|"writes attendance"| node_sheets
node_whatsapp -->|"saves attendance"| node_attendance_store
node_backfill -->|"writes attendance"| node_sheets
node_backfill -->|"saves attendance"| node_attendance_store
node_sheets -->|"appends rows"| node_google_sheets
node_attendance_store -->|"uses connection"| node_db
node_db -->|"connects and indexes"| node_mongodb_service
node_api -->|"queries attendance"| node_attendance_store
node_api -->|"checks health"| node_db
node_whatsapp -->|"updates status"| node_qr_state
node_api -->|"reads status"| node_qr_state
node_hr -->|"opens linking page"| node_api
node_api -->|"serves UI"| node_dashboard
node_sheets -->|"reads settings"| node_config
node_whatsapp -->|"reads settings"| node_config
node_backfill -->|"reads settings"| node_config

click node_main "https://github.com/unilights/whatsapp-bot/blob/main/src/index.js"
click node_whatsapp "https://github.com/unilights/whatsapp-bot/blob/main/src/whatsapp.js"
click node_backfill "https://github.com/unilights/whatsapp-bot/blob/main/src/backfill.js"
click node_parser "https://github.com/unilights/whatsapp-bot/blob/main/src/parser.js"
click node_keywords "https://github.com/unilights/whatsapp-bot/blob/main/src/parser-config.js"
click node_dedupe "https://github.com/unilights/whatsapp-bot/blob/main/src/processed-ids.js"
click node_config "https://github.com/unilights/whatsapp-bot/blob/main/src/config.js"
click node_sheets "https://github.com/unilights/whatsapp-bot/blob/main/src/sheets.js"
click node_attendance_store "https://github.com/unilights/whatsapp-bot/blob/main/src/attendance-store.js"
click node_db "https://github.com/unilights/whatsapp-bot/blob/main/src/db.js"
click node_api "https://github.com/unilights/whatsapp-bot/blob/main/src/api.js"
click node_qr_state "https://github.com/unilights/whatsapp-bot/blob/main/src/qr-state.js"
click node_dashboard "https://github.com/unilights/whatsapp-bot/blob/main/public/index.html"

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_whatsapp,node_backfill toneBlue
class node_parser,node_keywords,node_dedupe,node_config,node_google_sheets,node_mongodb_service toneAmber
class node_sheets,node_attendance_store,node_db toneMint
class node_api,node_qr_state,node_dashboard toneRose
class node_hr,node_whatsapp_service toneIndigo
```

## Components

### Message ingestion

- [Runtime startup](https://github.com/unilights/whatsapp-bot/blob/main/src/index.js): `src/index.js`
- [WhatsApp client](https://github.com/unilights/whatsapp-bot/blob/main/src/whatsapp.js): `src/whatsapp.js`
- [History backfill](https://github.com/unilights/whatsapp-bot/blob/main/src/backfill.js): `src/backfill.js`

### Attendance processing

- [Message parser](https://github.com/unilights/whatsapp-bot/blob/main/src/parser.js): `src/parser.js`
- [Type keywords](https://github.com/unilights/whatsapp-bot/blob/main/src/parser-config.js): `src/parser-config.js`
- [Processed IDs](https://github.com/unilights/whatsapp-bot/blob/main/src/processed-ids.js): `src/processed-ids.js`
- [Runtime configuration](https://github.com/unilights/whatsapp-bot/blob/main/src/config.js): `src/config.js`

### Attendance storage

- [Sheet writer](https://github.com/unilights/whatsapp-bot/blob/main/src/sheets.js): `src/sheets.js`
- [Attendance store](https://github.com/unilights/whatsapp-bot/blob/main/src/attendance-store.js): `src/attendance-store.js`
- [MongoDB connection](https://github.com/unilights/whatsapp-bot/blob/main/src/db.js): `src/db.js`

### Linking and analytics

- [HTTP API](https://github.com/unilights/whatsapp-bot/blob/main/src/api.js): `src/api.js`
- [QR connection state](https://github.com/unilights/whatsapp-bot/blob/main/src/qr-state.js): `src/qr-state.js`
- [Dashboard UI](https://github.com/unilights/whatsapp-bot/blob/main/public/index.html): `public/index.html`

### Other components

- **HR operator**
- **WhatsApp group**
- **Google Sheets**
- **MongoDB**

## Connections

- HR operator → WhatsApp client: sends messages (evidence: `README.md`)
- Runtime startup → MongoDB connection: connects (evidence: `src/index.js`)
- Runtime startup → HTTP API: starts (evidence: `src/index.js`)
- Runtime startup → WhatsApp client: starts (evidence: `src/index.js`)
- WhatsApp group → WhatsApp client: delivers events (evidence: `src/whatsapp.js`)
- WhatsApp client → Message parser: parses messages (evidence: `src/whatsapp.js`)
- History backfill → WhatsApp group: fetches history (evidence: `src/backfill.js`)
- WhatsApp client → History backfill: starts on ready (evidence: `src/whatsapp.js`)
- History backfill → Message parser: parses messages (evidence: `src/backfill.js`)
- Message parser → Type keywords: matches types (evidence: `src/parser.js`)
- WhatsApp client → Processed IDs: checks and records IDs (evidence: `src/whatsapp.js`)
- History backfill → Processed IDs: checks and records IDs (evidence: `src/backfill.js`)
- WhatsApp client → Sheet writer: writes attendance (evidence: `src/whatsapp.js`)
- WhatsApp client → Attendance store: saves attendance (evidence: `src/whatsapp.js`)
- History backfill → Sheet writer: writes attendance (evidence: `src/backfill.js`)
- History backfill → Attendance store: saves attendance (evidence: `src/backfill.js`)
- Sheet writer → Google Sheets: appends rows (evidence: `src/sheets.js`)
- Attendance store → MongoDB connection: uses connection (evidence: `src/attendance-store.js`)
- MongoDB connection → MongoDB: connects and indexes (evidence: `src/db.js`)
- HTTP API → Attendance store: queries attendance (evidence: `src/api.js`)
- HTTP API → MongoDB connection: checks health (evidence: `src/api.js`)
- WhatsApp client → QR connection state: updates status (evidence: `src/whatsapp.js`)
- HTTP API → QR connection state: reads status (evidence: `src/api.js`)
- HR operator → HTTP API: opens linking page (evidence: `README.md`)
- HTTP API → Dashboard UI: serves UI (evidence: `src/api.js`)
- Sheet writer → Runtime configuration: reads settings (evidence: `src/sheets.js`)
- WhatsApp client → Runtime configuration: reads settings (evidence: `src/whatsapp.js`)
- History backfill → Runtime configuration: reads settings (evidence: `src/backfill.js`)
