# chickenai/zalo-node architecture

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

- Interactive diagram: https://gitdiagram.com/chickenai/zalo-node
- Repository: https://github.com/chickenai/zalo-node

## Overview

##### Project type and purpose
- This is **an n8n community node plugin** that embeds itself into an existing n8n instance.
- It provides **automations for Zalo Web** by simulating a browser session, exposing actions (send message, group management, user management, message triggers) as n8n nodes.
- No standalone frontend or backend service; it runs inside the n8n host process.

##### File structure
Top‑level:
- **credentials/** – TypeScript files defining credential schemas (N8nApi, ZaloApi).
- **nodes/** – One folder per node, each with `.node.ts` (runtime logic) and optional Description files (`*.node.ts`, `*Description.ts`).
– ZaloLoginByQR, ZaloGroup, ZaloMessageTrigger, ZaloSendMessage, ZaloUser
- **index.js** – Entry point that registers all nodes and credentials with n8n.
- **gulpfile.js** – Build script to transpile TS to JS.
- **tsconfig.json**, **package.json**, lockfiles, linters, and editor configs.

##### README for insights
- Describes each node’s operations and event triggers.
- Emphasizes the in‑process nature (no external APIs beyond Zalo Web).
- Mentions dependency on a browser‑automation library (ZCA‑JS).

##### Main components and interactions
a. **n8n Host (core runtime & UI)**
b. **Node Plugin**
- **Index** – orchestrates registration of credentials and nodes.
- **Credentials Module** – defines how Zalo login tokens are stored and retrieved.
- **Node Modules** (ZaloLoginByQR, ZaloGroup, ZaloUser, ZaloSendMessage, ZaloMessageTrigger)
- Each node has:
– **Description** (metadata for the n8n editor)
– **Node Class** (execute() logic)
- **Build Tools** – Gulp for transpilation
c. **Browser‑Automation Engine (ZCA‑JS, likely wraps Puppeteer/Playwright)**
- Simulates a Chromium session to interact with Zalo Web UI.
d. **Zalo Web**
- The external service being automated.

Relationships:
1. **n8n Workflow** invokes a Node instance.
2. Node code uses stored **ZaloApi credentials** to instantiate a headless browser session via **ZCA‑JS**.
3. Browser session navigates to **Zalo Web**, executes actions (click, type, read DOM).
4. Results return to the Node’s `execute()` method and propagate back into the workflow.

##### Architectural patterns and design principles
- **Plugin architecture**: Clear separation between host (n8n) and extension (this module).
- **Modular Nodes**: Each feature encapsulated as an individual node following n8n’s Node interface.
- **Credential abstraction**: Central credential management reused by multiple nodes.
- **Browser automation as a service**: All nodes share a browser session handler.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Layer
    Host["n8n Host"]:::host

    %% Plugin Layer
    subgraph "Plugin Components"
        direction TB
        Index["Plugin Entry (Index)"]:::plugin
        Gulp["Build Tools (Gulp)"]:::plugin

        subgraph "Credentials Module"
            direction TB
            CredN8n["N8nApi Credentials"]:::plugin
            CredZalo["ZaloApi Credentials"]:::plugin
        end

        subgraph "Node Modules"
            direction TB
            QR["ZaloLoginByQR Node"]:::plugin
            Group["ZaloGroup Node"]:::plugin
            Trigger["ZaloMessageTrigger Node"]:::plugin
            Send["ZaloSendMessage Node"]:::plugin
            User["ZaloUser Node"]:::plugin
        end
    end

    %% Browser Automation and External Service
    Browser["Browser-Automation Engine (ZCA-JS)"]:::external
    ZaloWeb["Zalo Web"]:::external

    %% Connections
    Host -->|"load/register"| Index
    Index -->|"build"| Gulp
    Index -->|"registerCredentials"| CredN8n
    Index -->|"registerCredentials"| CredZalo
    Index -->|"registerNodes"| QR
    Index -->|"registerNodes"| Group
    Index -->|"registerNodes"| Trigger
    Index -->|"registerNodes"| Send
    Index -->|"registerNodes"| User

    Host -->|"execute() call"| QR
    Host -->|"execute() call"| Group
    Host -->|"execute() call"| Trigger
    Host -->|"execute() call"| Send
    Host -->|"execute() call"| User

    QR -->|"headless browser commands"| Browser
    Group -->|"headless browser commands"| Browser
    Trigger -->|"headless browser commands"| Browser
    Send -->|"headless browser commands"| Browser
    User -->|"headless browser commands"| Browser

    Browser -->|"HTTP/DOM interactions"| ZaloWeb
    ZaloWeb -->|"page DOM read/write"| Browser
    Browser -->|"results"| QR
    Browser -->|"results"| Group
    Browser -->|"results"| Trigger
    Browser -->|"results"| Send
    Browser -->|"results"| User

    QR -->|"workflow output"| Host
    Group -->|"workflow output"| Host
    Trigger -->|"workflow output"| Host
    Send -->|"workflow output"| Host
    User -->|"workflow output"| Host

    %% Click Events
    click Index "https://github.com/chickenai/zalo-node/blob/dev/index.js"
    click Gulp "https://github.com/chickenai/zalo-node/blob/dev/gulpfile.js"
    click CredN8n "https://github.com/chickenai/zalo-node/blob/dev/credentials/N8nApi.credentials.ts"
    click CredZalo "https://github.com/chickenai/zalo-node/blob/dev/credentials/ZaloApi.credentials.ts"
    click QR "https://github.com/chickenai/zalo-node/blob/dev/nodes/ZaloLoginByQR/ZaloLoginByQR.node.ts"
    click Group "https://github.com/chickenai/zalo-node/blob/dev/nodes/ZaloGroup/ZaloGroup.node.ts"
    click Group "https://github.com/chickenai/zalo-node/blob/dev/nodes/ZaloGroup/ZaloGroupDescription.ts"
    click Trigger "https://github.com/chickenai/zalo-node/blob/dev/nodes/ZaloMessageTrigger/ZaloMessageTrigger.node.ts"
    click Send "https://github.com/chickenai/zalo-node/blob/dev/nodes/ZaloSendMessage/ZaloSendMessage.node.ts"
    click User "https://github.com/chickenai/zalo-node/blob/dev/nodes/ZaloUser/ZaloUser.node.ts"
    click User "https://github.com/chickenai/zalo-node/blob/dev/nodes/ZaloUser/ZaloUserDescription.ts"

    %% Styles
    classDef host fill:#add8e6,stroke:#333,stroke-width:1px
    classDef plugin fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
```
