# nabilekowahyudi/service-desk-bot architecture

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

- Interactive diagram: https://gitdiagram.com/nabilekowahyudi/service-desk-bot
- Repository: https://github.com/nabilekowahyudi/service-desk-bot

## Overview

This is a WhatsApp IT ServiceDesk bot: employees submit requests through a guided conversation, the bot validates them against ManageEngine, creates tickets, and routes authorization approvals and technician replies. The graph preserves the documented webhook/polling, dynamic configuration, security, and media capabilities. Source evidence is sampled, so undocumented runtime wiring is omitted rather than inferred.

Main entry points: [`src/handlers/message.handler.js`](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/handlers/message.handler.js) (Conversation state machine), [`src/services/ticket.service.js`](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/ticket.service.js) (Ticket API and user lookup), [`src/services/notification.service.js`](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/notification.service.js) (Ticket update tracking), [`src/services/whatsapp.service.js`](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/whatsapp.service.js) (WhatsApp client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Runtime entry"]
  node_whatsapp["WhatsApp client"]
  node_server["HTTP server and webhooks<br/>[index.js]"]
end

subgraph group_conversation["Employee workflow"]
  node_handler["Conversation state machine<br/>[message.handler.js]"]
  node_validators["Input validation<br/>[validators.js]"]
  node_media["WhatsApp media download"]
end

subgraph group_manageengine["ManageEngine integration"]
  node_ticket["Ticket API and user lookup<br/>[ticket.service.js]"]
  node_categories["Category mapping cache"]
  node_meconfig["Dynamic service configuration"]
  node_endpoints["Request categories and endpoints<br/>[endpoints.js]"]
end

subgraph group_followup["Approvals and updates"]
  node_notifications["Ticket update tracking"]
  node_approval["Authorization approvals"]
end

subgraph group_foundation["State and safeguards"]
  node_sessions[("Conversation sessions<br/>[session.service.js]")]
  node_encrypted["Encrypted JSON store<br/>[encrypted-store.js]"]
  node_protection["Ticket protection"]
  node_logger["Redacting logger<br/>[logger.js]"]
end

node_employee(("Employee"))
node_admin(("Service admin"))
node_manageengine["ManageEngine SDP"]

node_employee -->|"sends messages"| node_whatsapp
node_whatsapp -->|"routes messages"| node_handler
node_handler -->|"validates input"| node_validators
node_handler -->|"loads and saves"| node_sessions
node_handler -->|"validates employee and submits"| node_ticket
node_handler -->|"uses category map"| node_categories
node_handler -->|"selects request form"| node_endpoints
node_handler -->|"tracks submitted tickets"| node_notifications
node_handler -->|"starts authorization flow"| node_approval
node_handler -->|"applies ticket safeguards"| node_protection
node_handler -.->|"downloads attachments"| node_media
node_ticket -->|"calls ServiceDesk API"| node_manageengine
node_categories -->|"fetches categories"| node_manageengine
node_categories -->|"uses API configuration"| node_endpoints
node_meconfig -.->|"resolves configuration"| node_manageengine
node_ticket -->|"uses category mapping"| node_categories
node_ticket -->|"uses dynamic IDs"| node_meconfig
node_ticket -->|"uses endpoint settings"| node_endpoints
node_manageengine -->|"pushes ticket updates"| node_server
node_server -->|"triggers immediate check"| node_notifications
node_notifications -->|"polls tracked tickets"| node_manageengine
node_notifications -->|"fetches ticket and user data"| node_ticket
node_notifications -->|"checks pending approvals"| node_approval
node_notifications -->|"sends employee updates"| node_whatsapp
node_approval -->|"sends approval prompts"| node_whatsapp
node_admin -->|"calls admin endpoints"| node_server
node_server -->|"refreshes category cache"| node_categories
node_sessions -->|"logs session errors"| node_logger
node_approval -->|"persists pending approvals"| node_encrypted
node_notifications -->|"persists ticket tracking"| node_encrypted
node_handler -->|"persists rate limits"| node_encrypted
node_encrypted -->|"logs storage errors"| node_logger
node_handler -->|"records workflow events"| node_logger
node_whatsapp -->|"records client events"| node_logger
node_ticket -->|"records API events"| node_logger

click node_whatsapp "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/whatsapp.service.js"
click node_server "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/index.js"
click node_handler "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/handlers/message.handler.js"
click node_validators "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/validators.js"
click node_media "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/wa-media-download.js"
click node_ticket "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/ticket.service.js"
click node_categories "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/category.service.js"
click node_meconfig "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/me-config.service.js"
click node_endpoints "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/config/endpoints.js"
click node_notifications "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/notification.service.js"
click node_approval "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/approval.service.js"
click node_sessions "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/session.service.js"
click node_encrypted "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/encrypted-store.js"
click node_protection "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/ticket-protection.js"
click node_logger "https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/logger.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_whatsapp,node_server toneBlue
class node_handler,node_validators,node_media toneAmber
class node_ticket,node_categories,node_meconfig,node_endpoints toneMint
class node_notifications,node_approval toneRose
class node_sessions,node_encrypted,node_protection,node_logger,node_employee,node_admin,node_manageengine toneIndigo
```

## Components

### Runtime entry

- [WhatsApp client](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/whatsapp.service.js): `src/services/whatsapp.service.js`
- [HTTP server and webhooks](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/index.js): `index.js`

### Employee workflow

- [Conversation state machine](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/handlers/message.handler.js): `src/handlers/message.handler.js`
- [Input validation](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/validators.js): `src/utils/validators.js`
- [WhatsApp media download](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/wa-media-download.js): `src/utils/wa-media-download.js`

### ManageEngine integration

- [Ticket API and user lookup](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/ticket.service.js): `src/services/ticket.service.js`
- [Category mapping cache](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/category.service.js): `src/services/category.service.js`
- [Dynamic service configuration](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/me-config.service.js): `src/services/me-config.service.js`
- [Request categories and endpoints](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/config/endpoints.js): `src/config/endpoints.js`

### Approvals and updates

- [Ticket update tracking](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/notification.service.js): `src/services/notification.service.js`
- [Authorization approvals](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/approval.service.js): `src/services/approval.service.js`

### State and safeguards

- [Conversation sessions](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/services/session.service.js): `src/services/session.service.js`
- [Encrypted JSON store](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/encrypted-store.js): `src/utils/encrypted-store.js`
- [Ticket protection](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/ticket-protection.js): `src/utils/ticket-protection.js`
- [Redacting logger](https://github.com/nabilekowahyudi/service-desk-bot/blob/main/src/utils/logger.js): `src/utils/logger.js`

### Other components

- **Employee**
- **Service admin**
- **ManageEngine SDP**

## Connections

- Employee → WhatsApp client: sends messages (evidence: `README.md`)
- WhatsApp client → Conversation state machine: routes messages (evidence: `src/services/whatsapp.service.js`)
- Conversation state machine → Input validation: validates input (evidence: `src/handlers/message.handler.js`)
- Conversation state machine → Conversation sessions: loads and saves (evidence: `src/handlers/message.handler.js`)
- Conversation state machine → Ticket API and user lookup: validates employee and submits (evidence: `src/handlers/message.handler.js`)
- Conversation state machine → Category mapping cache: uses category map (evidence: `src/handlers/message.handler.js`)
- Conversation state machine → Request categories and endpoints: selects request form (evidence: `src/handlers/message.handler.js`)
- Conversation state machine → Ticket update tracking: tracks submitted tickets (evidence: `src/handlers/message.handler.js`)
- Conversation state machine → Authorization approvals: starts authorization flow (evidence: `src/handlers/message.handler.js`)
- Conversation state machine → Ticket protection: applies ticket safeguards (evidence: `src/handlers/message.handler.js`)
- Conversation state machine → WhatsApp media download: downloads attachments (evidence: `src/handlers/message.handler.js`)
- Ticket API and user lookup → ManageEngine SDP: calls ServiceDesk API (evidence: `src/services/ticket.service.js`)
- Category mapping cache → ManageEngine SDP: fetches categories (evidence: `src/services/category.service.js`)
- Category mapping cache → Request categories and endpoints: uses API configuration (evidence: `src/services/category.service.js`)
- Dynamic service configuration → ManageEngine SDP: resolves configuration
- Ticket API and user lookup → Category mapping cache: uses category mapping (evidence: `src/services/ticket.service.js`)
- Ticket API and user lookup → Dynamic service configuration: uses dynamic IDs (evidence: `src/services/ticket.service.js`)
- Ticket API and user lookup → Request categories and endpoints: uses endpoint settings (evidence: `src/services/ticket.service.js`)
- ManageEngine SDP → HTTP server and webhooks: pushes ticket updates (evidence: `README.md`)
- HTTP server and webhooks → Ticket update tracking: triggers immediate check (evidence: `README.md`)
- Ticket update tracking → ManageEngine SDP: polls tracked tickets (evidence: `README.md`)
- Ticket update tracking → Ticket API and user lookup: fetches ticket and user data (evidence: `src/services/notification.service.js`)
- Ticket update tracking → Authorization approvals: checks pending approvals (evidence: `src/services/notification.service.js`)
- Ticket update tracking → WhatsApp client: sends employee updates (evidence: `README.md`)
- Authorization approvals → WhatsApp client: sends approval prompts (evidence: `src/services/approval.service.js`)
- Service admin → HTTP server and webhooks: calls admin endpoints (evidence: `README.md`)
- HTTP server and webhooks → Category mapping cache: refreshes category cache (evidence: `index.js`)
- Conversation sessions → Redacting logger: logs session errors (evidence: `src/services/session.service.js`)
- Authorization approvals → Encrypted JSON store: persists pending approvals (evidence: `src/utils/encrypted-store.js`)
- Ticket update tracking → Encrypted JSON store: persists ticket tracking (evidence: `src/utils/encrypted-store.js`)
- Conversation state machine → Encrypted JSON store: persists rate limits (evidence: `src/utils/encrypted-store.js`)
- Encrypted JSON store → Redacting logger: logs storage errors (evidence: `src/utils/encrypted-store.js`)
- Conversation state machine → Redacting logger: records workflow events (evidence: `src/handlers/message.handler.js`)
- WhatsApp client → Redacting logger: records client events (evidence: `src/services/whatsapp.service.js`)
- Ticket API and user lookup → Redacting logger: records API events (evidence: `src/services/ticket.service.js`)