# danog/madelineproto architecture

> Architecture diagram of the GitHub repository danog/madelineproto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danog/madelineproto
- Repository: https://github.com/danog/madelineproto

## Overview

MadelineProto is an asynchronous PHP client for Telegram’s MTProto API, supporting phone-number and bot-token accounts without using the Bot API. A client starts or logs in, invokes Telegram methods through its API namespaces, and exchanges MTProto traffic with Telegram; incoming updates can be converted to typed events and dispatched to user handlers. Other major capabilities include file transfer, broadcasting, IPC/persistence, private and group calls, and VoIP media. The graph follows the README and tree; where implementation excerpts were unavailable, subsystem wiring is shown only when the documented client workflow supports it.

Main entry points: [`src/Namespace`](https://github.com/danog/madelineproto/tree/v8/src/Namespace) (API namespaces), [`src/MTProto.php`](https://github.com/danog/madelineproto/blob/v8/src/MTProto.php) (MTProto engine), [`src/API.php`](https://github.com/danog/madelineproto/blob/v8/src/API.php) (Client API), [`src/EventHandler.php`](https://github.com/danog/madelineproto/blob/v8/src/EventHandler.php) (Event handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client API"]
  node_api["Client API<br/>[API.php]"]
  node_auth["Login and auth<br/>[AuthKeyHandler.php]"]
  node_namespaces["API namespaces"]
  node_state[("Session state")]
end

subgraph group_protocol["MTProto transport"]
  node_mtproto["MTProto engine<br/>[MTProto.php]"]
  node_connection["Connections<br/>[Connection.php]"]
  node_crypto["Protocol crypto<br/>[Crypt.php]"]
end

subgraph group_updates["Updates and handlers"]
  node_updates["Update processing<br/>[UpdateHandler.php]"]
  node_events["Event handlers<br/>[EventHandler.php]"]
  node_filters["Update filters"]
  node_plugins["Plugins"]
end

subgraph group_features["Messaging features"]
  node_broadcast["Broadcasting<br/>[Broadcast.php]"]
  node_files["File transfer<br/>[Files.php]"]
  node_ipc["IPC<br/>[Client.php]"]
end

subgraph group_calls["Calls and media"]
  node_privatecalls["Private calls"]
  node_groupcalls["Group calls"]
  node_voip["VoIP media<br/>[VoIPLoop.php]"]
  node_media["Media codecs<br/>[Matroska.php]"]
end

node_user(("Application"))
node_telegram(("Telegram"))

node_user -->|"starts client"| node_api
node_api -->|"logs in"| node_auth
node_api -->|"exposes methods"| node_namespaces
node_namespaces -->|"invokes methods"| node_mtproto
node_auth -->|"establishes keys"| node_mtproto
node_mtproto -->|"sends traffic"| node_connection
node_connection -->|"exchanges MTProto"| node_telegram
node_mtproto -->|"encrypts messages"| node_crypto
node_mtproto -->|"persists session"| node_state
node_telegram -->|"delivers updates"| node_updates
node_updates -->|"dispatches events"| node_events
node_events -->|"applies filters"| node_filters
node_events -->|"loads handlers"| node_plugins
node_user -->|"configures broadcast"| node_broadcast
node_broadcast -->|"sends messages"| node_namespaces
node_user -->|"requests transfer"| node_files
node_files -->|"calls upload methods"| node_namespaces
node_user -->|"uses client remotely"| node_ipc
node_api -->|"supports IPC"| node_ipc
node_user -->|"controls calls"| node_privatecalls
node_privatecalls -->|"runs media loop"| node_voip
node_user -->|"controls group calls"| node_groupcalls
node_groupcalls -->|"runs media loop"| node_voip
node_voip -->|"processes streams"| node_media
node_privatecalls -->|"signals calls"| node_namespaces
node_groupcalls -->|"signals calls"| node_namespaces

click node_api "https://github.com/danog/madelineproto/blob/v8/src/API.php"
click node_auth "https://github.com/danog/madelineproto/blob/v8/src/MTProtoSession/AuthKeyHandler.php"
click node_namespaces "https://github.com/danog/madelineproto/tree/v8/src/Namespace"
click node_state "https://github.com/danog/madelineproto/tree/v8/src/Settings/Database"
click node_mtproto "https://github.com/danog/madelineproto/blob/v8/src/MTProto.php"
click node_connection "https://github.com/danog/madelineproto/blob/v8/src/Connection.php"
click node_crypto "https://github.com/danog/madelineproto/blob/v8/src/MTProtoTools/Crypt.php"
click node_updates "https://github.com/danog/madelineproto/blob/v8/src/MTProtoTools/UpdateHandler.php"
click node_events "https://github.com/danog/madelineproto/blob/v8/src/EventHandler.php"
click node_filters "https://github.com/danog/madelineproto/tree/v8/src/EventHandler/Filter"
click node_plugins "https://github.com/danog/madelineproto/blob/v8/src/PluginEventHandler.php"
click node_broadcast "https://github.com/danog/madelineproto/blob/v8/src/Broadcast/Broadcast.php"
click node_files "https://github.com/danog/madelineproto/blob/v8/src/MTProtoTools/Files.php"
click node_ipc "https://github.com/danog/madelineproto/blob/v8/src/Ipc/Client.php"
click node_privatecalls "https://github.com/danog/madelineproto/blob/v8/src/Tgcalls/PrivateCallController.php"
click node_groupcalls "https://github.com/danog/madelineproto/blob/v8/src/GroupCall/GroupCallController.php"
click node_voip "https://github.com/danog/madelineproto/blob/v8/src/Loop/VoIPLoop.php"
click node_media "https://github.com/danog/madelineproto/blob/v8/src/Matroska.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_auth,node_namespaces,node_state toneBlue
class node_mtproto,node_connection,node_crypto toneAmber
class node_updates,node_events,node_filters,node_plugins toneMint
class node_broadcast,node_files,node_ipc toneRose
class node_privatecalls,node_groupcalls,node_voip,node_media,node_user,node_telegram toneIndigo
```

## Components

### Client API

- [Client API](https://github.com/danog/madelineproto/blob/v8/src/API.php): `src/API.php`
- [Login and auth](https://github.com/danog/madelineproto/blob/v8/src/MTProtoSession/AuthKeyHandler.php): `src/MTProtoSession/AuthKeyHandler.php`
- [API namespaces](https://github.com/danog/madelineproto/tree/v8/src/Namespace): `src/Namespace`
- [Session state](https://github.com/danog/madelineproto/tree/v8/src/Settings/Database): `src/Settings/Database`

### MTProto transport

- [MTProto engine](https://github.com/danog/madelineproto/blob/v8/src/MTProto.php): `src/MTProto.php`
- [Connections](https://github.com/danog/madelineproto/blob/v8/src/Connection.php): `src/Connection.php`
- [Protocol crypto](https://github.com/danog/madelineproto/blob/v8/src/MTProtoTools/Crypt.php): `src/MTProtoTools/Crypt.php`

### Updates and handlers

- [Update processing](https://github.com/danog/madelineproto/blob/v8/src/MTProtoTools/UpdateHandler.php): `src/MTProtoTools/UpdateHandler.php`
- [Event handlers](https://github.com/danog/madelineproto/blob/v8/src/EventHandler.php): `src/EventHandler.php`
- [Update filters](https://github.com/danog/madelineproto/tree/v8/src/EventHandler/Filter): `src/EventHandler/Filter`
- [Plugins](https://github.com/danog/madelineproto/blob/v8/src/PluginEventHandler.php): `src/PluginEventHandler.php`

### Messaging features

- [Broadcasting](https://github.com/danog/madelineproto/blob/v8/src/Broadcast/Broadcast.php): `src/Broadcast/Broadcast.php`
- [File transfer](https://github.com/danog/madelineproto/blob/v8/src/MTProtoTools/Files.php): `src/MTProtoTools/Files.php`
- [IPC](https://github.com/danog/madelineproto/blob/v8/src/Ipc/Client.php): `src/Ipc/Client.php`

### Calls and media

- [Private calls](https://github.com/danog/madelineproto/blob/v8/src/Tgcalls/PrivateCallController.php): `src/Tgcalls/PrivateCallController.php`
- [Group calls](https://github.com/danog/madelineproto/blob/v8/src/GroupCall/GroupCallController.php): `src/GroupCall/GroupCallController.php`
- [VoIP media](https://github.com/danog/madelineproto/blob/v8/src/Loop/VoIPLoop.php): `src/Loop/VoIPLoop.php`
- [Media codecs](https://github.com/danog/madelineproto/blob/v8/src/Matroska.php): `src/Matroska.php`

### Other components

- **Application**
- **Telegram**

## Connections

- Application → Client API: starts client
- Client API → Login and auth: logs in
- Client API → API namespaces: exposes methods
- API namespaces → MTProto engine: invokes methods
- Login and auth → MTProto engine: establishes keys
- MTProto engine → Connections: sends traffic
- Connections → Telegram: exchanges MTProto
- MTProto engine → Protocol crypto: encrypts messages
- MTProto engine → Session state: persists session
- Telegram → Update processing: delivers updates
- Update processing → Event handlers: dispatches events
- Event handlers → Update filters: applies filters
- Event handlers → Plugins: loads handlers
- Application → Broadcasting: configures broadcast
- Broadcasting → API namespaces: sends messages
- Application → File transfer: requests transfer
- File transfer → API namespaces: calls upload methods
- Application → IPC: uses client remotely
- Client API → IPC: supports IPC
- Application → Private calls: controls calls
- Private calls → VoIP media: runs media loop
- Application → Group calls: controls group calls
- Group calls → VoIP media: runs media loop
- VoIP media → Media codecs: processes streams
- Private calls → API namespaces: signals calls
- Group calls → API namespaces: signals calls