# telegrammessenger/mtproxy architecture

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

- Interactive diagram: https://gitdiagram.com/telegrammessenger/mtproxy
- Repository: https://github.com/telegrammessenger/mtproxy

## Overview

##### Xác định loại dự án và mục đích
- Đây là một service network proxy (viết bằng C) trung gian giữa client Telegram (MTProto) và server Telegram.
- Không có giao diện người dùng; hoạt động chính là bắt kết nối TCP từ client, giải mã/điều phối, mã hoá/giải mã, rồi chuyển tiếp đến server Telegram.

##### Phân tích cấu trúc thư mục
- Thư mục “net”: xử lý socket, kết nối TCP, sự kiện I/O, HTTP-server cho thống kê.
- Thư mục “crypto”: cài đặt AES, SHA, MD5, CRC, dùng để mã hoá/generate hash.
- Thư mục “mtproto”: logic MTProto (cấu hình, phân tích gói tin, proxy logic).
- Thư mục “engine”: lớp trung gian điều phối RPC, signal, vòng lặp chính.
- Thư mục “jobs”: scheduler để chạy task nền.
- Thư mục “common”: các tiện ích chung (logging, parse-config, queue, time, RPC-const…).
- Thư mục “vv”: cấu trúc dữ liệu cây phục vụ thống kê/IO.

##### Các thành phần chính (block components)
a. Proxy Master Process
- Đọc config, spawn worker processes (hoặc threads).
b. Worker Processes / Threads
- Mỗi worker gồm:
- Module Network (net):
- net-thread, net-events, net-tcp-connections, net-http-server (cổng stats).
- Module MTProto (mtproto):
- mtproto-proxy, parser, config.
- Module Crypto (crypto):
- AES-NI, SHA1/SHA256, MD5, CRC32…
- Engine (engine):
- Điều phối RPC, event loop, signal handling.
- Job Scheduler (jobs) & Utilities (common, vv).
c. External Systems
- Telegram Servers (MTProto endpoints).
- DNS Resolver (qua common/resolver).
- HTTP Client cho stats (qua loopback).

##### Mối quan hệ và luồng dữ liệu
- Client MTProto (Internet) ──(TCP CONNECT)──► net-tcp-connections
- net-events → engine vòng lặp → phân phối tới mtproto-proxy
- mtproto-proxy → sử dụng crypto để giải/mã gói → chuyển tiếp tới Telegram Servers
- Telegram Servers trả về → ngược dòng qua mtproto → net → client
- Bên cạnh đó: local HTTP GET tới net-http-server/stats → net → vv-tree + common-stats → trả JSON/text

##### Các pattern kiến trúc
- Event-driven, non-blocking I/O (epoll/kqueue) trong net-events.
- Worker model: master process + N workers (–M option).
- Modular layering: Network layer, Protocol layer, Crypto layer, Engine layer, Utility layer.
- Cấu hình động: parse-config chung cho tất cả module.

##### Hướng dẫn vẽ sơ đồ
- Chia thành các nhóm khối (clusters) theo tầng:
[Clients] – [Network Module] – [Engine] – [MTProto Logic] – [Crypto Module] – [Telegram Servers]
- Bên cạnh, vẽ thêm luồng stats:
[Loopback HTTP Client] → [net-http-server] → [vv-tree / common-stats]
- Vẽ khối “Master Process” ở phía trên, nối xuống các “Worker Process #1…#N”.
- Mỗi khối con (ví dụ Network Module) có thể in tên file chính hoặc submodule.
- Dùng màu sắc:
- Xanh dương: Network
- Đỏ: Crypto
- Xanh lá: MTProto
- Tím: Engine
- Xám: Common/Utilities
- Hình dạng:
- Hình chữ nhật bo góc cho modules,
- Hình lục giác cho các service ngoài (Telegram, DNS),
- Hình tròn cho endpoint client.

##### Các yếu tố cần thể hiện chi tiết
- Nhãn rõ ràng cho từng component (ví dụ: net-tcp-rpc-server, mtproto-proxy.c,…).
- Số lượng worker (ví dụ M workers).
- Cổng dịch vụ (client port 443, stats port 8888).
- File config (proxy-secret, proxy-multi.conf).
- Luồng life-cycle: từ khởi động (Makefile → mtproto-proxy exec) → drop privileges → bind port → loop xử lý.
- Cơ chế random padding (dd prefix) nếu muốn nhấn mạnh feature tuỳ chọn.

Khi hoàn thiện, sơ đồ sẽ cho cái nhìn tổng quát và chi tiết về cách các module C kết hợp vận hành thành một MTProxy service. Hãy kiểm tra lại tính chính xác của mũi tên, màu và label trước khi trình bày.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client((Client MTProto)):::client
    LoopClient((Loopback HTTP Client)):::client
    Telegram[/Telegram Servers/]:::external
    DNS[/DNS Resolver/]:::external

    subgraph "Master Process"
        MP["Proxy Master Process"]:::common
    end

    MP -->|"spawn M workers"| Worker[/"Worker Processes (M)"/]:::common

    subgraph "Worker Process"
        direction TB

        subgraph "Network Module"
            NT["net-thread"]:::network
            NE["net-events"]:::network
            NC["net-tcp-connections"]:::network
            NH["net-http-server (port 8888)"]:::network
        end

        subgraph "Engine Module"
            Eng["Engine"]:::engine
        end

        subgraph "MTProto Logic"
            Proto["mtproto-proxy"]:::mtproto
            MPCfg["mtproto-config"]:::mtproto
        end

        subgraph "Crypto Module"
            AES["AES-NI"]:::crypto
            SHA["SHA1/SHA256"]:::crypto
            MD5["MD5"]:::crypto
            CRC["CRC32"]:::crypto
        end

        subgraph "Job & Utilities"
            Jobs["jobs"]:::common
            ParseCfg["parse-config"]:::common
            VV["vv-tree"]:::common
        end

        NT --> NE
        NE --> Eng
        NC --> Eng
        Eng --> Proto
        Proto --> AES
        Proto --> SHA
        Proto --> MD5
        Proto --> CRC
        CRC --> Telegram
        DNS --> Proto
        NH --> VV
        NH --> ParseCfg
    end

    Client -->|"TCP CONNECT (port 443)"| NC
    Telegram -->|"response"| NC
    LoopClient -->|"HTTP GET /stats"| NH

    click MP "https://github.com/telegrammessenger/mtproxy/blob/master/mtproto/mtproto-proxy.c"
    click NT "https://github.com/telegrammessenger/mtproxy/blob/master/net/net-thread.c"
    click NE "https://github.com/telegrammessenger/mtproxy/blob/master/net/net-events.c"
    click NC "https://github.com/telegrammessenger/mtproxy/blob/master/net/net-tcp-connections.c"
    click NH "https://github.com/telegrammessenger/mtproxy/blob/master/net/net-http-server.c"
    click Proto "https://github.com/telegrammessenger/mtproxy/blob/master/mtproto/mtproto-proxy.c"
    click MPCfg "https://github.com/telegrammessenger/mtproxy/blob/master/mtproto/mtproto-config.c"
    click AES "https://github.com/telegrammessenger/mtproxy/blob/master/crypto/aesni256.c"
    click SHA "https://github.com/telegrammessenger/mtproxy/blob/master/common/sha1.c"
    click MD5 "https://github.com/telegrammessenger/mtproxy/blob/master/common/md5.c"
    click CRC "https://github.com/telegrammessenger/mtproxy/blob/master/common/crc32.c"
    click Jobs "https://github.com/telegrammessenger/mtproxy/blob/master/jobs/jobs.c"
    click ParseCfg "https://github.com/telegrammessenger/mtproxy/blob/master/common/parse-config.c"
    click VV "https://github.com/telegrammessenger/mtproxy/blob/master/vv/vv-tree.c"
    click DNS "https://github.com/telegrammessenger/mtproxy/blob/master/common/resolver.c"

    classDef network fill:#cce5ff,stroke:#004085,color:#004085;
    classDef crypto fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef mtproto fill:#d4edda,stroke:#155724,color:#155724;
    classDef engine fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef common fill:#fdfdfe,stroke:#818182,color:#818182;
    classDef client fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#343a40,color:#343a40;
```
