# cietsthydroxide/miki_whatsappbot architecture

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

- Interactive diagram: https://gitdiagram.com/cietsthydroxide/miki_whatsappbot
- Repository: https://github.com/cietsthydroxide/miki_whatsappbot

## Overview

##### Project Type and Purpose
- This is a Node.js–based WhatsApp chat bot (“Miki WhatsApp Bot”).
- It uses an event‐driven architecture to listen to incoming messages, route them to command handlers, optionally persist or read data, then send replies back through the WhatsApp API.

##### File Structure Analysis
- Top-level files
- index.js – entry point that bootstraps the bot
- bot_settings.json – configuration (API keys, prefixes, etc.)
- message.txt – templated messages or help text
- core/ directory – the heart of the system
- _client.js / _client-test.js – wrapper around WhatsApp connection (login, event subscription)
- _command.js – central dispatcher that parses an incoming message into a command name + arguments
- _database.js – JSON file I/O layer, reads/writes core/database/*.json
- _utils.js – helper functions (formatting, randomization, etc.)
- main.js – brings together client, command dispatcher, database
- commands/ directory – each JS file implements a single bot command, following a consistent interface (execute, name, description)
- classes/WarningPoint.js – domain class used by commands (represents a user warning entry)
- core/database/ – persistent data store in JSON (data.json for live, data-test.json for tests)
- test.js – lightweight smoke test harness

##### Key Insights from README
- Minimal README points to a repository migration, but project purpose/self-description is that of a modular WhatsApp bot with pluggable commands and simple JSON persistence.

a. Main Components
1. WhatsApp Client Adapter
2. Command Dispatcher
3. Command Modules
4. Database Layer
5. Utility & Domain Classes
6. Configuration (bot_settings.json)
b. Relationships & Data Flow
- Incoming WhatsApp message → Client Adapter
- Client Adapter emits “message” event → Command Dispatcher
- Dispatcher parses message, looks up correct Command Module → execute()
- Command Module may read/write via Database Layer → JSON files
- Command Module may use Utility functions or Domain Classes
- Command Module returns response → Dispatcher → Client Adapter → WhatsApp
c. Architectural Patterns
- Event-driven (publish/subscribe on incoming messages)
- Command pattern (each command is a self-contained handler)
- Layered (Adapter → Dispatcher → Modules → Persistence)
d. Relevant Technologies
- Node.js runtime
- whatsapp-web.js (or similar) in core/_client
- JSON file storage for persistence
- Custom ES6 classes for domain logic

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        WA["WhatsApp"]:::external
    end

    subgraph "Adapter Layer"
        ClientAdapter["WhatsApp Client Adapter"]:::core
        ClientAdapterTest["Client Adapter Test"]:::core
    end

    subgraph "Application Logic"
        Entry["Entry Point (index.js)"]:::core
        Main["Main Application Bootstrapper"]:::core
        Dispatcher["Command Dispatcher"]:::core
    end

    subgraph "Commands Layer"
        CommandsDir["Commands Directory"]:::command
        Ping["Command: ping"]:::command
        Warn["Command: warn"]:::command
        Help["Command: __help"]:::command
        Afk["Command: afk"]:::command
        Upper["Command: uppercase"]:::command
    end

    subgraph "Persistence Layer"
        DBLayer["Database Layer"]:::core
        DataLive["data.json"]:::config
        DataTest["data-test.json"]:::config
    end

    subgraph "Utility & Domain"
        Utils["Utility Functions"]:::core
        WarningClass["WarningPoint Class"]:::domain
    end

    subgraph "Config & Templates"
        Config["Configuration (bot_settings.json)"]:::config
        Templates["Messages Template (message.txt)"]:::config
    end

    subgraph "Tests"
        SmokeTest["Smoke Test Harness"]:::test
    end

    %% Data Flow
    WA -->|"raw message"| ClientAdapter
    ClientAdapter -->|"message event"| Dispatcher
    Dispatcher -->|"invoke execute() on ping"| Ping
    Dispatcher -->|"invoke execute() on warn"| Warn
    Dispatcher -->|"invoke execute() on __help"| Help
    Dispatcher -->|"invoke execute() on afk"| Afk
    Dispatcher -->|"invoke execute() on uppercase"| Upper
    Ping -->|"read/write"| DBLayer
    Warn -->|"read/write"| DBLayer
    DBLayer -->|"update JSON"| DataLive
    DBLayer -->|"update JSON (test)"| DataTest
    Ping -->|"use"| Utils
    Warn -->|"use"| Utils
    Warn -->|"use"| WarningClass
    Dispatcher -->|"respond"| ClientAdapter
    ClientAdapter -->|"send reply"| WA

    Entry -->|"bootstraps"| Main
    Main -->|"initializes"| ClientAdapter
    Main -->|"initializes"| Dispatcher
    Main -->|"registers commands from"| CommandsDir
    Main -->|"loads config"| Config
    Main -->|"loads templates"| Templates
    Main -->|"initializes DBLayer"| DBLayer

    CommandsDir --> Ping
    CommandsDir --> Warn
    CommandsDir --> Help
    CommandsDir --> Afk
    CommandsDir --> Upper

    SmokeTest -.->|"runs smoke tests against"| Main

    %% Click Events
    click ClientAdapter "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/core/_client.js"
    click ClientAdapterTest "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/core/_client-test.js"
    click Dispatcher "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/core/_command.js"
    click Main "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/core/main.js"
    click Entry "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/index.js"
    click DBLayer "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/core/_database.js"
    click DataLive "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/core/database/data.json"
    click DataTest "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/core/database/data-test.json"
    click Utils "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/core/_utils.js"
    click Config "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/bot_settings.json"
    click Templates "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/message.txt"
    click WarningClass "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/classes/WarningPoint.js"
    click CommandsDir "https://github.com/cietsthydroxide/miki_whatsappbot/tree/main/commands/"
    click Ping "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/commands/ping.js"
    click Warn "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/commands/warn.js"
    click Help "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/commands/__help.js"
    click Afk "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/commands/afk.js"
    click Upper "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/commands/uppercase.js"
    click SmokeTest "https://github.com/cietsthydroxide/miki_whatsappbot/blob/main/test.js"

    %% Styles
    classDef external fill:#C3E0FF,stroke:#1B6CA8;color:#000
    classDef core fill:#D5F5E3,stroke:#27AE60;color:#000
    classDef command fill:#FCF3CF,stroke:#F1C40F;color:#000
    classDef config fill:#F2F3F4,stroke:#95A5A6;color:#000
    classDef domain fill:#FADBD8,stroke:#E74C3C,color:#000
    classDef test fill:#F5EEF8,stroke:#8E44AD,color:#000
```
