# its-vrxxdev/zlapi architecture

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

- Interactive diagram: https://gitdiagram.com/its-vrxxdev/zlapi
- Repository: https://github.com/its-vrxxdev/zlapi

## Overview

##### Project Type and Purpose
- **Type**: Open-source Python SDK / library
- **Purpose**: Provide both synchronous (“simple”) and asynchronous (“Async”) Python interfaces to interact with Zalo’s web endpoints—supporting login via cookies, sending/receiving messages, managing groups, listening for events in real time (WebSocket or polling).

##### High-Level Components
a. **User Application**
– Your bot script or application imports `zlapi` or `zlapi.Async`/`zlapi.simple`, instantiates `ZaloAPI`, registers handlers, then calls `.listen()`.
b. **Public API Layer**
– `zlapi/Async/__init__.py` & `zlapi/simple/__init__.py`
– These expose `ZaloAPI` classes: one async (uses `asyncio` + WebSockets), one “simple” (thread-based + requests).
c. **Core Client and Session Management**
– `zlapi/_client.py`
– `zlapi/_core.py`
– Manage HTTP session (cookies, IMEI header), authentication, endpoint URLs.
d. **State Management**
– `zlapi/_state.py` + `zlapi/Async/_state.py` + `zlapi/simple/_state.py`
– Track tokens, user info, thread info, pending events.
e. **Event & Message Parsing**
– `zlapi/_parse_message.py`, `zlapi/_message.py`, `zlapi/_aevents.py`
– Convert raw JSON or WebSocket frames into Python `Message`, `EventObject`, `Mention`, `MessageStyle`, etc.
f. **Threads & Concurrency**
– `zlapi/_threads.py` (for “requests” polling)
– `Async/_async.py` (for event loop + WebSocket)
g. **Utilities & Logging**
– `zlapi/_util.py` (HTTP helpers, retry logic)
– `zlapi/logging.py` (internal logging wrappers)
h. **Models & Exceptions**
– `zlapi/models.py` (data classes: `ThreadType`, `EventType`)
– `zlapi/_exception.py` (custom exceptions)

##### External Services
- **Zalo Web Endpoints** (HTTP REST + WebSocket)
- **Browser Extension** (for IMEI & Cookies acquisition) – optional, not part of library code but depicted as external input source.

##### Data Flows & Interactions
1. **Initialization**
– User code → instantiates `ZaloAPI`, passing cookies & IMEI → Core Client sets up session state.
2. **Listen / Receive**
– For Async: `websocket.connect` → incoming frames → `_parse_message` → emit `onMessage`/`onEvent` to user handlers.
– For Simple: polling thread calls HTTP endpoints → receives JSON → same pipeline.
3. **API Calls (send/modify)**
– User calls `.sendMessage()`, `.createGroup()`, etc. → Public API → Core Client (`_client`) → HTTP POST → Zalo.
– Response flows back → State module updates if needed → returns to user.

##### Architectural Patterns & Principles
- **Modular Package Structure**: separation between API layer, client logic, state, parsing, and models.
- **Strategy for Concurrency**: two parallel strategies (asyncio vs thread/polling) under a unified interface pattern.
- **Event-Driven**: user-provided callbacks are invoked via an internal dispatcher.
- **Adapter / Facade**: `ZaloAPI` classes adapt raw HTTP/WebSocket to Pythonic methods.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    subgraph "User Application"
        UserApp["User Application\n(imports ZaloAPI,\nregisters handlers)"]:::user
    end

    %% Public API Layer
    subgraph "Public API Layer"
        AsyncAPI["ZaloAPI Async"]:::user
        SimpleAPI["ZaloAPI Simple"]:::user
    end

    %% Internal Modules
    subgraph "Internal Modules"
        subgraph "Client & Core"
            Client["Client Logic"]:::internal
            Core["Core Utilities"]:::internal
        end
        subgraph "State Management"
            StateCommon["State Common"]:::internal
            StateAsync["State Async"]:::internal
            StateSimple["State Simple"]:::internal
        end
        subgraph "Parsing & Events"
            ParseMsg["Parser"]:::internal
            MsgModels["Message Models"]:::internal
            AsyncEvents["Async Events"]:::internal
        end
        subgraph "Concurrency"
            Threads["Polling Threads"]:::internal
            AsyncLoop["Async Event Loop"]:::internal
        end
        subgraph "Utilities & Logging"
            Util["HTTP Helpers & Retry"]:::internal
            Log["Logging Wrappers"]:::internal
        end
        subgraph "Models & Exceptions"
            DataModels["Data Models"]:::model
            Exceptions["Custom Exceptions"]:::model
        end
    end

    %% External Services
    subgraph "External Services"
        ZaloHTTP["Zalo HTTP REST"]:::external
        ZaloWS["Zalo WebSocket"]:::external
        CookieFetch["Browser Extension\n(Cookies & IMEI)"]:::external
    end

    %% Connections: User to API
    UserApp -->|"uses"| AsyncAPI
    UserApp -->|"uses"| SimpleAPI

    %% API to Client/Core
    AsyncAPI -->|"calls"| Client
    SimpleAPI -->|"calls"| Client
    AsyncAPI -->|"connects"| ZaloWS
    SimpleAPI -->|"triggers"| Threads

    %% Client & Core relationships
    Client -->|"utilizes"| Core
    Client -->|"reads/writes"| StateCommon
    Client -->|"reads/writes"| StateAsync
    Client -->|"reads/writes"| StateSimple
    StateCommon -->|"syncs"| StateAsync
    StateCommon -->|"syncs"| StateSimple
    Client -->|"invokes"| Util
    Client -->|"logs via"| Log
    Client -->|"uses"| DataModels
    Client -->|"raises"| Exceptions

    %% Concurrency flows
    Threads -->|"polls"| ZaloHTTP
    ZaloHTTP -->|"returns JSON"| ParseMsg
    AsyncLoop -->|"receives frames"| ZaloWS
    ZaloWS -->|"WebSocket frame"| AsyncLoop
    AsyncLoop -->|"forwards"| ParseMsg

    %% Parsing & Event dispatch
    ParseMsg -->|"creates"| MsgModels
    ParseMsg -->|"emits"| AsyncEvents
    AsyncEvents -->|"calls handlers"| UserApp
    ParseMsg -->|"dispatches to"| SimpleAPI

    %% API calls to external
    Client -->|"HTTP POST /chat/sendMessage"| ZaloHTTP
    AsyncAPI -->|"WebSocket connect"| ZaloWS

    %% External input
    CookieFetch -->|"provides"| Client

    %% Click Events
    click AsyncAPI "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/Async/__init__.py"
    click SimpleAPI "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/simple/__init__.py"
    click Client "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/_client.py"
    click Core "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/_core.py"
    click StateCommon "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/_state.py"
    click StateAsync "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/Async/_state.py"
    click StateSimple "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/simple/_state.py"
    click ParseMsg "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/_parse_message.py"
    click MsgModels "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/_message.py"
    click AsyncEvents "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/_aevents.py"
    click Threads "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/_threads.py"
    click AsyncLoop "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/Async/_async.py"
    click Util "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/_util.py"
    click Log "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/logging.py"
    click DataModels "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/models.py"
    click Exceptions "https://github.com/its-vrxxdev/zlapi/blob/master/zlapi/_exception.py"

    %% Styles
    classDef user fill:#e6ffe6,stroke:#2d7f2d,color:#000
    classDef internal fill:#f2f2f2,stroke:#999,color:#000
    classDef external fill:#e6f0ff,stroke:#1f4e8c,color:#000
    classDef model fill:#fff4e6,stroke:#bf8b00,color:#000
```
