# sqkhanh/zaloclientlua architecture

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

- Interactive diagram: https://gitdiagram.com/sqkhanh/zaloclientlua
- Repository: https://github.com/sqkhanh/zaloclientlua

## Overview

##### Project Type and Purpose
- This is a hybrid Java application that embeds Lua scripting for handling callbacks. Its primary purpose is to establish a secure WebSocket connection to the Zalo messaging service (chat.zalo.me) and facilitate interactions by leveraging both Java (for core connection logic and API calls) and Lua (for event handling and callbacks). It also includes custom DLL libraries for encryption and decryption during data exchange.

##### File Structure for Architectural Clues
- The “lib/java” directory holds the core Java code including key components such as:
– Zalo.java and ZaloAPI.java for establishing and managing WebSocket connections and API interactions.
– ControllerListener.java which likely manages incoming WebSocket events.
– Configuration files (ZaloConfig.java and ZaloConfigHelper.java) that manage settings (e.g., from config.yml).
- The “src” directory is predominantly Lua:
– “src/api” contains Lua scripts that serve as an API layer to interface with Java.
– “src/callback” (with its event subdirectories) encompasses scripts for different types of callback handling (webchat events, group messages, command handling, etc.).
- The presence of main.lua and several Lua files in API and callback directories indicates that Lua is tightly integrated to process incoming events and then delegate processing to the Java side.
- Additional folders such as “tutorial” (images, etc.) and configuration files (config.yml) support deployment and user instructions.

##### Core Components
- WebSocket Client Module:
- Java API & Core Logic:
- A sub-component for Configuration Management (ZaloConfig.java, ZaloConfigHelper.java, config.yml) that feeds necessary settings into the system.
- Lua Scripting Engine:
- Embedded Lua environment (main.lua, src/api, and src/callback folders) that processes callbacks upon receiving events. This module is responsible for custom business logic and for invoking Java API methods when required.
- Callback Handling Module:
- Various Lua callbacks (onOpen.lua, onClose.lua, onError.lua, onMessage.lua, etc.) that listen for incoming server events and trigger corresponding actions.
- External DLL Libraries:
- A component to represent the custom DLLs used for encrypting and decrypting data. Note that these interact likely with the Java API layer for secure data transactions.
- User/CLI Interface:
- CLI or front-end component (Release.exe as mentioned in the README) that users interact with to start the application and issue commands.

##### Architectural Patterns and Design Principles
- Dual-Language Integration: Emphasize how the system uses Java for the core connection and high-performance network tasks while Lua is embedded for flexible event and callback handling.
- Separation of Concerns: Clearly separate network connectivity, callback processing, configuration, and encryption logic (via DLL) into distinct components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User & Configuration Layer"
        CLI["User CLI (Release.rar)"]:::external
        Config["Configuration Management (ZaloConfig.java, ZaloConfigHelper.java, config.yml)"]:::external
        DLL["DLL Libraries (Encryption/Decryption)"]:::external
    end

    subgraph "Java Core Layer"
        JavaCore["Java WebSocket Module (Zalo.java, ZaloAPI.java, ControllerListener.java)"]:::java
    end

    subgraph "Lua Scripting Layer"
        LuaCallback["Lua Callback Module (src/callback)"]:::lua
        JavaLua["Java-Lua API Integration (src/api)"]:::lua
    end

    ChatServer["chat.zalo.me"]:::external

    CLI -->|"userCommand"| JavaCore
    Config -->|"configUpdate"| JavaCore
    DLL -->|"encryptDecrypt"| JavaCore

    JavaCore -->|"sendEvent"| LuaCallback
    LuaCallback -->|"invokeJava"| JavaLua
    JavaLua -->|"apiCall"| JavaCore

    JavaCore -->|"connect"| ChatServer

    click JavaCore "https://github.com/sqkhanh/zaloclientlua/tree/main/lib/java/com/khanhdz/bot/zalo"
    click JavaCore "https://github.com/sqkhanh/zaloclientlua/blob/main/lib/java/com/khanhdz/bot/zalo/controller/ControllerListener.java"
    click Config "https://github.com/sqkhanh/zaloclientlua/tree/main/lib/java/com/khanhdz/config"
    click Config "https://github.com/sqkhanh/zaloclientlua/blob/main/config.yml"
    click LuaCallback "https://github.com/sqkhanh/zaloclientlua/tree/main/src/callback"
    click JavaLua "https://github.com/sqkhanh/zaloclientlua/tree/main/src/api/java"
    click CLI "https://github.com/sqkhanh/zaloclientlua/blob/main/Release.rar"

    classDef java fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef lua fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
