# chickenai/multizlogin architecture

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

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

## Overview

##### Project type and purpose
- MultiZlogin is a full-stack, monolithic Node.js application built on Express.
- It provides both a web UI (EJS templates) for human operators and a RESTful API for integration with other systems (e.g., n8n).
- Core purpose: manage multiple Zalo accounts (login via QR), support proxy usage per account, configure per-account webhooks, track connection status, and expose an API for external automation.

##### File structure
- src/server.js & src/app.js: application entrypoints (HTTP server, middleware setup).
- src/routes/*: routing layer, separates UI routes (EJS views) from API routes (/api/*).
- src/services/*: business-logic layer (authService, proxyService, webhookService).
- src/api/zalo/zalo.js: Zalo integration module using zca-js library.
- src/config/webhookConfig.json + .env: global & per-account configuration.
- data/ and zalo_data/: persistent JSON storage for cookies, proxies, webhook configs (no external DB).
- Dockerfile, docker-compose.yaml & scripts/: containerization, volume setup, build/publish automation.

##### Main components
a. Client Layer
- Browser UI (EJS pages served over HTTPS)
- External API Consumer (e.g., n8n workflows calling /api/* endpoints)
b. Web/Application Server
- Express.js HTTP server
- Routing Layer: UI routes vs API routes
- Controllers: lightweight handlers in routes/*.js
- Service Layer: encapsulates interactions with Zalo, proxies, webhook logic
c. Persistence Layer
- File-based JSON storage (mounted volume via Docker) for:
- cookies/users.json
- proxies.json
- webhook-config.json
d. External Services
- Zalo Web API (third-party service)
- n8n (or other webhook target)
e. Deployment/Infrastructure
- Docker Container (multizlogin_zalo-server)
- Docker Compose orchestration (bind mounts for zalo_data)
- Helper scripts for build, publish, migration

##### Relationships and interactions
- Browser ⇄ Express (UI GET/POST)
- Express routes ⇄ Service layer (business methods)
- Service layer ⇄ JSON storage (read/write)
- authService/webhookService ⇄ Zalo API (login, fetch events)
- webhookService ⇄ External webhook targets (n8n)
- API consumers ⇄ Express API routes (X-API-Key auth)

##### Architectural patterns & design principles
- MVC-like separation: Views (EJS) ↔ Controllers (routes) ↔ Services
- Single process monolith for simplicity, layered internally
- Environment-driven config (12-factor) via .env and webhookConfig.json
- Container-first design: all state in external volume, stateless app container

##### Final recommendations
- Every logical component (routes vs services vs storage) rather than lumping everything under “server.”
- Docker volume mapping for zalo_data as the persistent layer.
- Security/auth (API key in header, session cookie management) near the boundary.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & API Integration Layers
    subgraph "User Interaction" 
        Browser["Browser (UI)"]:::ui
    end
    subgraph "API Integration"
        n8n["n8n Workflow"]:::ext
    end

    %% Express Monolith
    subgraph "Express Monolith" 
        direction TB
        subgraph "Routing Layer"
            direction TB
            UI_Routes["UI Routes (EJS)"]:::server
            API_Routes["API Routes (REST API)"]:::server
        end
        subgraph "Service Layer"
            direction TB
            AuthService["authService"]:::server
            ProxyService["proxyService"]:::server
            WebhookService["webhookService"]:::server
            ZaloModule["Zalo Integration Module"]:::server
        end
        subgraph "Data Layer"
            direction TB
            Cookies["cookies/users.json"]:::data
            Proxies["proxies.json"]:::data
            WebhookConfig["webhook-config.json"]:::data
        end
    end

    %% External Services
    ZaloAPI["Zalo Web API"]:::ext
    WebhookTarget["External Webhook Targets"]:::ext

    %% Connections
    Browser -->|"HTTPS"| UI_Routes
    n8n -->|"HTTP POST /api"| API_Routes

    UI_Routes --> AuthService
    UI_Routes --> ProxyService
    UI_Routes --> WebhookService

    API_Routes -->|"X-API-Key auth"| AuthService
    API_Routes --> ProxyService
    API_Routes --> WebhookService

    AuthService -->|"calls zca-js"| ZaloModule
    WebhookService --> ZaloModule
    WebhookService -->|"Webhook POST"| WebhookTarget

    AuthService --> Cookies
    ProxyService --> Proxies
    WebhookService --> WebhookConfig

    ZaloModule -->|"HTTP"| ZaloAPI

    %% Click Events
    click Browser "https://github.com/chickenai/multizlogin/blob/main/src/views/index.ejs"
    click UI_Routes "https://github.com/chickenai/multizlogin/blob/main/src/routes/ui.js"
    click API_Routes "https://github.com/chickenai/multizlogin/blob/main/src/routes/api.js"
    click AuthService "https://github.com/chickenai/multizlogin/blob/main/src/services/authService.js"
    click ProxyService "https://github.com/chickenai/multizlogin/blob/main/src/services/proxyService.js"
    click WebhookService "https://github.com/chickenai/multizlogin/blob/main/src/services/webhookService.js"
    click ZaloModule "https://github.com/chickenai/multizlogin/blob/main/src/api/zalo/zalo.js"
    click Cookies "https://github.com/chickenai/multizlogin/blob/main/data/cookies/users.json"
    click Proxies "https://github.com/chickenai/multizlogin/blob/main/data/proxies.json"
    click WebhookConfig "https://github.com/chickenai/multizlogin/blob/main/data/zalo_data/webhook-config.json"

    %% Styles
    classDef ui fill:#CCE5FF,stroke:#007BFF,color:#004085
    classDef server fill:#D4EDDA,stroke:#28A745,color:#155724
    classDef data fill:#F8F9FA,stroke:#6C757D,color:#343A40
    classDef ext fill:#FFF3CD,stroke:#FFC107,color:#856404
```
