# idlanyor/zapota architecture

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

- Interactive diagram: https://gitdiagram.com/idlanyor/zapota
- Repository: https://github.com/idlanyor/zapota

## Overview

Kanata is a WhatsApp bot with a plugin-command workflow, local bot state, and optional HTTP/Socket.IO interfaces. Its separate Kanata Core service provides identity, user, session, and finance APIs to the bot and PHP client; finance extraction remains in the bot before storage in Core. The graph also preserves major command capabilities and the Werewolf game subsystem. Relationships for unsampled command families and PHP pages are based on README statements; source excerpts show selected runtime calls, not every route.

Main entry points: [`src/handlers/messageHandler.js`](https://github.com/idlanyor/zapota/blob/main/src/handlers/messageHandler.js) (Message handler), [`core/src/app.js`](https://github.com/idlanyor/zapota/blob/main/core/src/app.js) (Core HTTP API), [`src/commands`](https://github.com/idlanyor/zapota/tree/main/src/commands) (Command plugins), [`core/src/database/pool.js`](https://github.com/idlanyor/zapota/blob/main/core/src/database/pool.js) (MariaDB access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["WhatsApp bot runtime"]
  node_wa_transport["Transport adapters<br/>[client.js]"]
  node_message_handler["Message handler<br/>[messageHandler.js]"]
  node_message_flow["Message flow<br/>[messageFlow.js]"]
  node_commands["Command loader<br/>[commands.js]"]
end

subgraph group_features["Bot capabilities"]
  node_plugins["Command plugins"]
  node_ai["AI commands<br/>[ds.js]"]
  node_media["Media downloaders"]
  node_group_commands["Group commands"]
  node_finance_commands["Finance commands"]
  node_werewolf["Werewolf game<br/>[service.js]"]
end

subgraph group_botstate["Bot state and APIs"]
  node_finance_service["Finance extraction<br/>[financeService.js]"]
  node_bot_db[("Bot database<br/>[adapter.js]")]
  node_webhook["Bot webhook<br/>[webhookApi.js]"]
  node_core_client["Core API client<br/>[kanataCore.js]"]
end

subgraph group_core["Kanata Core"]
  node_core_api["Core HTTP API<br/>[app.js]"]
  node_core_auth["Service authentication"]
  node_identity["Identity service<br/>[service.js]"]
  node_users["User service<br/>[service.js]"]
  node_core_finance["Finance service<br/>[service.js]"]
  node_core_db[("MariaDB access<br/>[pool.js]")]
end

subgraph group_web["PHP web client"]
  node_php_ui["PHP web pages<br/>[index.php]"]
  node_php_api["PHP Core client<br/>[api.php]"]
end

node_wa_user(("WhatsApp user"))
node_whatsapp{{"WhatsApp"}}
node_external_services{{"External integrations"}}

node_wa_user -->|"sends messages"| node_whatsapp
node_whatsapp -->|"transports messages"| node_wa_transport
node_wa_transport -->|"delivers events"| node_message_handler
node_message_handler -->|"delegates processing"| node_message_flow
node_message_handler -->|"dispatches commands"| node_commands
node_commands -->|"loads plugins"| node_plugins
node_message_handler -->|"saves messages"| node_bot_db
node_message_flow -->|"requests AI response"| node_ai
node_message_handler -->|"routes game events"| node_werewolf
node_finance_commands -.->|"extracts transactions"| node_finance_service
node_finance_service -->|"stores finance data"| node_core_client
node_plugins -->|"provides download commands"| node_media
node_plugins -->|"provides group tools"| node_group_commands
node_plugins -->|"provides finance tools"| node_finance_commands
node_plugins -.->|"uses integrations"| node_external_services
node_core_client -->|"sends HMAC requests"| node_core_api
node_php_ui -->|"requests data"| node_php_api
node_php_api -->|"sends HTTP requests"| node_core_api
node_php_ui -->|"requests bot operations"| node_webhook
node_core_api -->|"authenticates services"| node_core_auth
node_core_api -->|"resolves identities"| node_identity
node_core_api -->|"handles user routes"| node_users
node_core_api -->|"handles finance routes"| node_core_finance
node_core_auth -->|"checks client records"| node_core_db
node_identity -->|"reads and writes identities"| node_core_db
node_users -->|"uses database queries"| node_core_db
node_core_finance -->|"uses database queries"| node_core_db
node_core_db -->|"connects to MariaDB"| node_external_services
node_webhook -->|"forwards Core requests"| node_core_client
node_message_handler -.->|"sends replies"| node_whatsapp

click node_wa_transport "https://github.com/idlanyor/zapota/blob/main/src/wa/client.js"
click node_message_handler "https://github.com/idlanyor/zapota/blob/main/src/handlers/messageHandler.js"
click node_message_flow "https://github.com/idlanyor/zapota/blob/main/src/handlers/messageFlow.js"
click node_commands "https://github.com/idlanyor/zapota/blob/main/src/lib/commands.js"
click node_plugins "https://github.com/idlanyor/zapota/tree/main/src/commands"
click node_ai "https://github.com/idlanyor/zapota/blob/main/src/commands/ai/ds.js"
click node_media "https://github.com/idlanyor/zapota/tree/main/src/commands/downloader"
click node_group_commands "https://github.com/idlanyor/zapota/tree/main/src/commands/group"
click node_finance_commands "https://github.com/idlanyor/zapota/tree/main/src/commands/finance"
click node_werewolf "https://github.com/idlanyor/zapota/blob/main/src/games/werewolf/service.js"
click node_finance_service "https://github.com/idlanyor/zapota/blob/main/src/services/financeService.js"
click node_bot_db "https://github.com/idlanyor/zapota/blob/main/src/database/adapter.js"
click node_webhook "https://github.com/idlanyor/zapota/blob/main/src/services/webhookApi.js"
click node_core_client "https://github.com/idlanyor/zapota/blob/main/src/services/kanataCore.js"
click node_core_api "https://github.com/idlanyor/zapota/blob/main/core/src/app.js"
click node_core_auth "https://github.com/idlanyor/zapota/blob/main/core/src/security/authenticateService.js"
click node_identity "https://github.com/idlanyor/zapota/blob/main/core/src/identity/service.js"
click node_users "https://github.com/idlanyor/zapota/blob/main/core/src/users/service.js"
click node_core_finance "https://github.com/idlanyor/zapota/blob/main/core/src/finance/service.js"
click node_core_db "https://github.com/idlanyor/zapota/blob/main/core/src/database/pool.js"
click node_php_ui "https://github.com/idlanyor/zapota/blob/main/php_client/index.php"
click node_php_api "https://github.com/idlanyor/zapota/blob/main/php_client/includes/api.php"

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_wa_transport,node_message_handler,node_message_flow,node_commands,node_wa_user toneBlue
class node_plugins,node_ai,node_media,node_group_commands,node_finance_commands,node_werewolf toneAmber
class node_finance_service,node_bot_db,node_webhook,node_core_client toneMint
class node_core_api,node_core_auth,node_identity,node_users,node_core_finance,node_core_db toneRose
class node_php_ui,node_php_api,node_whatsapp,node_external_services toneIndigo
```

## Components

### WhatsApp bot runtime

- [Transport adapters](https://github.com/idlanyor/zapota/blob/main/src/wa/client.js): `src/wa/client.js`
- [Message handler](https://github.com/idlanyor/zapota/blob/main/src/handlers/messageHandler.js): `src/handlers/messageHandler.js`
- [Message flow](https://github.com/idlanyor/zapota/blob/main/src/handlers/messageFlow.js): `src/handlers/messageFlow.js`
- [Command loader](https://github.com/idlanyor/zapota/blob/main/src/lib/commands.js): `src/lib/commands.js`

### Bot capabilities

- [Command plugins](https://github.com/idlanyor/zapota/tree/main/src/commands): `src/commands`
- [AI commands](https://github.com/idlanyor/zapota/blob/main/src/commands/ai/ds.js): `src/commands/ai/ds.js`
- [Media downloaders](https://github.com/idlanyor/zapota/tree/main/src/commands/downloader): `src/commands/downloader`
- [Group commands](https://github.com/idlanyor/zapota/tree/main/src/commands/group): `src/commands/group`
- [Finance commands](https://github.com/idlanyor/zapota/tree/main/src/commands/finance): `src/commands/finance`
- [Werewolf game](https://github.com/idlanyor/zapota/blob/main/src/games/werewolf/service.js): `src/games/werewolf/service.js`

### Bot state and APIs

- [Finance extraction](https://github.com/idlanyor/zapota/blob/main/src/services/financeService.js): `src/services/financeService.js`
- [Bot database](https://github.com/idlanyor/zapota/blob/main/src/database/adapter.js): `src/database/adapter.js`
- [Bot webhook](https://github.com/idlanyor/zapota/blob/main/src/services/webhookApi.js): `src/services/webhookApi.js`
- [Core API client](https://github.com/idlanyor/zapota/blob/main/src/services/kanataCore.js): `src/services/kanataCore.js`

### Kanata Core

- [Core HTTP API](https://github.com/idlanyor/zapota/blob/main/core/src/app.js): `core/src/app.js`
- [Service authentication](https://github.com/idlanyor/zapota/blob/main/core/src/security/authenticateService.js): `core/src/security/authenticateService.js`
- [Identity service](https://github.com/idlanyor/zapota/blob/main/core/src/identity/service.js): `core/src/identity/service.js`
- [User service](https://github.com/idlanyor/zapota/blob/main/core/src/users/service.js): `core/src/users/service.js`
- [Finance service](https://github.com/idlanyor/zapota/blob/main/core/src/finance/service.js): `core/src/finance/service.js`
- [MariaDB access](https://github.com/idlanyor/zapota/blob/main/core/src/database/pool.js): `core/src/database/pool.js`

### PHP web client

- [PHP web pages](https://github.com/idlanyor/zapota/blob/main/php_client/index.php): `php_client/index.php`
- [PHP Core client](https://github.com/idlanyor/zapota/blob/main/php_client/includes/api.php): `php_client/includes/api.php`

### Other components

- **WhatsApp user**
- **WhatsApp**
- **External integrations**

## Connections

- WhatsApp user → WhatsApp: sends messages (evidence: `README.md`)
- WhatsApp → Transport adapters: transports messages (evidence: `README.md`)
- Transport adapters → Message handler: delivers events (evidence: `README.md`)
- Message handler → Message flow: delegates processing (evidence: `src/handlers/messageHandler.js`)
- Message handler → Command loader: dispatches commands (evidence: `src/handlers/messageHandler.js`)
- Command loader → Command plugins: loads plugins (evidence: `README.md`)
- Message handler → Bot database: saves messages (evidence: `src/handlers/messageHandler.js`)
- Message flow → AI commands: requests AI response (evidence: `src/handlers/messageFlow.js`)
- Message handler → Werewolf game: routes game events (evidence: `src/handlers/messageHandler.js`)
- Finance commands → Finance extraction: extracts transactions (evidence: `README.md`)
- Finance extraction → Core API client: stores finance data (evidence: `README.md`)
- Command plugins → Media downloaders: provides download commands (evidence: `README.md`)
- Command plugins → Group commands: provides group tools (evidence: `README.md`)
- Command plugins → Finance commands: provides finance tools (evidence: `README.md`)
- Command plugins → External integrations: uses integrations (evidence: `README.md`)
- Core API client → Core HTTP API: sends HMAC requests (evidence: `README.md`)
- PHP web pages → PHP Core client: requests data (evidence: `php_client/index.php`)
- PHP Core client → Core HTTP API: sends HTTP requests (evidence: `README.md`)
- PHP web pages → Bot webhook: requests bot operations (evidence: `README.md`)
- Core HTTP API → Service authentication: authenticates services (evidence: `core/src/app.js`)
- Core HTTP API → Identity service: resolves identities (evidence: `core/src/app.js`)
- Core HTTP API → User service: handles user routes (evidence: `core/src/app.js`)
- Core HTTP API → Finance service: handles finance routes (evidence: `core/src/app.js`)
- Service authentication → MariaDB access: checks client records (evidence: `core/src/security/authenticateService.js`)
- Identity service → MariaDB access: reads and writes identities (evidence: `core/src/identity/service.js`)
- User service → MariaDB access: uses database queries (evidence: `core/src/users/service.js`)
- Finance service → MariaDB access: uses database queries (evidence: `core/src/finance/service.js`)
- MariaDB access → External integrations: connects to MariaDB (evidence: `README.md`)
- Bot webhook → Core API client: forwards Core requests (evidence: `src/services/webhookApi.js`)
- Message handler → WhatsApp: sends replies
