# cangpham/multizlogin architecture

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

- Interactive diagram: https://gitdiagram.com/cangpham/multizlogin
- Repository: https://github.com/cangpham/multizlogin

## Overview

##### Project Type and Purpose
- The project is a full-stack Node.js web application that manages multiple Zalo accounts. It supports functionalities like QR-based login, proxy integration, webhook configuration, and external API interactions.
- It includes several operational scripts and Docker deployment files, indicating a production-oriented and containerized environment that can also integrate with workflow automation tools (n8n).

##### File Structure and Key Directories
- Top-level files and directories to note:
- “src”: Contains the main source code organized into folders:
- api (for Zalo-specific API logic)
- config (with environment and webhook configuration files)
- routes (dividing endpoints into UI, general API, and index routes)
- services (business logic for authentication, proxy handling, and webhooks)
- views (EJS templates for various pages like login and administration)
- “data” and “zalo_data”: These serve as storages for cookie data, proxy configurations, and webhook settings.
- “scripts”: Houses various maintenance and migration scripts (e.g., for docker builds, cleaning for publishing, updating servers).
- Docker-related files (Dockerfile, docker-compose.yaml) indicate containerized deployment.

##### Main Components
a. User Interface
– Browser-based UI that renders EJS templates (login pages, dashboards for account and proxy management).
– Connects to the server via HTTP.
b. Application Server (Backend)
– The Node.js server is driven by Express (implicit from routes and middleware code) that handles both UI rendering and API requests.
– Routes are segmented into API endpoints (for accounts, webhooks, status) and UI endpoints.
c. Service Layer
– Authentication Service, Proxy Service, and Webhook Service (located under src/services) handle business logic.
– Event listeners (src/eventListeners.js) that likely monitor real-time events or webhook triggers.
d. API Layer
– API endpoints defined in src/routes/api.js, through which external systems or automation tools (n8n via webhook integration) interact.
– The API uses API-key based authentication as noted in the README.
e. Data Management
– File-based storage for cookies, proxies, and webhook configurations (directories/data and zalo_data).
f. External Integrations
– The dockerized environment set up through Dockerfile and docker-compose for running the application in containers.
– n8n integration: The project provides webhook URLs for incoming events, meaning the system interacts externally with an automation engine.
g. DevOps / Deployment Scripts
– A variety of scripts manage Docker builds, environment preparation, migration of data, and publishing (located in the “scripts” folder).

##### Relationships and Data Flow
- A client’s browser sends HTTP requests to the Node.js server.
- The Express server routes the requests to either render UI views (EJS templates) or to serve API responses.
- API routes invoke corresponding services (auth, proxy, webhook) which may retrieve or update data stored in local files (e.g., cookies, proxies.json).
- Webhook interactions: When events occur on Zalo, the incoming data is sent via the configured webhook URLs to both the MultiZlogin system and optionally to external systems like n8n.
- Docker components: Docker and docker-compose files encapsulate the application, and scripts support building, pushing, or updating Docker images.
- Maintenance scripts coordinate tasks such as cleaning sensitive data before publishing or migrating data structures.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The clear division between routes (handling incoming requests), services (implementing business logic), and views (rendering UI).
- Configuration-driven deployment: Use of environment files (.env & config) and Docker configurations that enable consistency across development and production environments.
- Modular design: The project is split into reusable modules (e.g., services, API endpoints) and organized by functionality.
- Integration via Webhooks and API key authentication ensures secure and decoupled communication with external systems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    A["Client Browser"]:::client

    %% Frontend Layer
    subgraph "User Interface Layer"
        UI["User Interface (Browser & EJS Views)"]:::ui
    end

    %% Application Server Layer
    subgraph "Application Server Layer"
        AS["Application Server (Express Server)"]:::server
        R["Routes (API,UI,Index)"]:::routes
    end

    %% Service Layer
    subgraph "Service Layer (Business Logic)"
        S["Services (auth, proxy, webhook)"]:::service
        EL["Event Listeners"]:::service
    end

    %% API Layer
    subgraph "API Layer (External API Endpoints)"
        API1["Zalo API"]:::api
        API2["API Routes"]:::api
    end

    %% Data Management
    subgraph "Data Management (Persistent File Storage)"
        DM1["data"]:::data
        DM2["zalo_data"]:::data
    end

    %% External Integrations
    subgraph "External Integrations (Docker & Webhooks)"
        EI1["Dockerfile"]:::external
        EI2["Docker Compose"]:::external
        EI3["New Docker Compose"]:::external
        EI4["Prepare Docker Script"]:::external
        EI5["Scripts: Prepare Docker"]:::external
        EI6["Config: Webhook"]:::external
    end

    %% DevOps / Deployment Scripts
    subgraph "DevOps / Deployment Scripts"
        DE1["Clean-for-Publish (clean-for-publish.sh)"]:::devops
        DE2["Fix Docker Build (fix-docker-build.sh)"]:::devops
        DE3["Migrate Structure (migrate-structure.js)"]:::devops
        DE4["Migrate to Zalo Data (migrate-to-zalo-data.sh)"]:::devops
        DE5["Restore After Publish (restore-after-publish.sh)"]:::devops
        DE6["Update Zalo Server (update-zalo-server.sh)"]:::devops
    end

    %% External Systems
    Z["External System: Zalo"]:::external
    N["External System: n8n"]:::external

    %% Connections
    A -->|"HTTPReq"| AS
    AS -->|"initializes"| R
    R -->|"renders"| UI
    UI -->|"displayed"| A

    AS -->|"calls"| S
    AS -->|"handles"| API2

    API2 -->|"delegates"| S

    S -->|"reads/writes"| DM1
    S -->|"reads/writes"| DM2
    EL -->|"event triggers"| DM1
    EL -->|"event triggers"| DM2

    S -->|"webhook/events"| EI6

    Z ---|"webhook"| API2
    N ---|"webhook"| API2

    DE1 ---|"deploy"| EI1

    %% Click Events
    click UI "https://github.com/cangpham/multizlogin/tree/main/src/views"
    click AS "https://github.com/cangpham/multizlogin/blob/main/src/server.js"
    click R "https://github.com/cangpham/multizlogin/tree/main/src/routes"
    click S "https://github.com/cangpham/multizlogin/tree/main/src/services"
    click EL "https://github.com/cangpham/multizlogin/blob/main/src/eventListeners.js"
    click API1 "https://github.com/cangpham/multizlogin/blob/main/src/api/zalo/zalo.js"
    click API2 "https://github.com/cangpham/multizlogin/blob/main/src/routes/api.js"
    click DM1 "https://github.com/cangpham/multizlogin/tree/main/data"
    click DM2 "https://github.com/cangpham/multizlogin/tree/main/zalo_data"
    click EI1 "https://github.com/cangpham/multizlogin/tree/main/Dockerfile"
    click EI2 "https://github.com/cangpham/multizlogin/blob/main/docker-compose.yaml"
    click EI3 "https://github.com/cangpham/multizlogin/blob/main/docker-compose.new.yaml"
    click EI4 "https://github.com/cangpham/multizlogin/blob/main/prepare-docker.sh"
    click EI5 "https://github.com/cangpham/multizlogin/blob/main/scripts/prepare-docker.sh"
    click EI6 "https://github.com/cangpham/multizlogin/tree/main/src/config"
    click DE1 "https://github.com/cangpham/multizlogin/blob/main/scripts/clean-for-publish.sh"
    click DE2 "https://github.com/cangpham/multizlogin/blob/main/scripts/fix-docker-build.sh"
    click DE3 "https://github.com/cangpham/multizlogin/blob/main/scripts/migrate-structure.js"
    click DE4 "https://github.com/cangpham/multizlogin/blob/main/scripts/migrate-to-zalo-data.sh"
    click DE5 "https://github.com/cangpham/multizlogin/blob/main/scripts/restore-after-publish.sh"
    click DE6 "https://github.com/cangpham/multizlogin/blob/main/scripts/update-zalo-server.sh"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef ui fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef server fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef routes fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef service fill:#F7DC6F,stroke:#B7950B,stroke-width:2px;
    classDef api fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef data fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef devops fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
```
