# davidegalilei/piltover architecture

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

- Interactive diagram: https://gitdiagram.com/davidegalilei/piltover
- Repository: https://github.com/davidegalilei/piltover

## Overview

##### Main Components

a) Core Server Components:
- Transport Layer Handler (handles different transport protocols)
- Authorization System
- Message Processing Engine
- TL (Type Language) Serialization System
- Session Management
- Cryptographic Components

b) External Interfaces:
- TCP Socket Interface
- WebSocket Proxy Interface
- Client Connection Handlers

**[Client Layer]**
- ↓ ↑
**[Transport Layer]**
- ↓ ↑
**[Protocol Layer]**
- ↓ ↑
**[Core Processing Layer]**
- ↓ ↑
**[Storage Layer]**

##### Component Details

a) Client Layer:
- Supported clients (Telegram Desktop, WebK, WebZ, Pyrogram, Telethon)
- Both TCP and WebSocket connection paths

b) Transport Layer:
- Different transport types (Abridged, Intermediate, Padded Intermediate, TCP Full, Obfuscated)
- WebSocket proxy component for web clients

c) Protocol Layer:
- MTProto implementation
- Authorization key generation
- RSA encryption/decryption
- Message identification and sequencing

d) Core Processing Layer:
- TL Serialization/Deserialization (JIT-based)
- Message handlers
- Update system
- Session management

e) Storage Layer (planned/future):
- Auth keys storage
- Message storage
- User data storage
- Updates storage

##### Implementation Details to Highlight

- Flow of the authorization process
- Where RSA key pairs are used
- Demonstrate message flow through the different transport layers
- How the JIT TL serialization works

##### Connection Flows

- Initial connection and transport detection
- Authorization key generation
- Normal message processing
- Update handling

##### Additional Elements

- Version/layer information for TL schemas
- Security checkpoints and validation steps
- Where future components will be integrated

Remember to include notes about:
- The experimental nature of the security implementation
- The JIT nature of TL serialization
- The multiple transport protocol support
- The WebSocket proxy requirement for web clients

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Clients
        TC[Telegram Desktop]
        WK[WebK]
        WZ[WebZ]
        PG[Pyrogram]
        TN[Telethon]
    end

    subgraph "Transport Layer"
        direction TB
        CH["Connection Handler"]:::core
        click CH "https://github.com/DavideGalilei/piltover/blob/master/piltover/connection.py"
        
        subgraph "Transport Types"
            direction TB
            AB["Abridged"]
            IM["Intermediate"]
            PI["Padded Intermediate"]
            TF["TCP Full"]
            OB["Obfuscated"]
        end

        WP["WebSocket Proxy"]:::proxy
        click WP "https://github.com/DavideGalilei/piltover/blob/master/tools/websocket_proxy.py"
        
        BS["Stream Handler"]:::core
        click BS "https://github.com/DavideGalilei/piltover/blob/master/piltover/utils/buffered_stream.py"
    end

    subgraph "Protocol Layer"
        direction TB
        MT["MTProto Implementation"]
        AK["Authorization Key Gen"]:::security
        RS["RSA Encryption/Decryption"]:::security
        click RS "https://github.com/DavideGalilei/piltover/blob/master/piltover/utils/rsa_utils.py"
        MS["Message Sequencing"]
    end

    subgraph "Core Processing"
        direction TB
        SV["Main Server"]:::core
        click SV "https://github.com/DavideGalilei/piltover/blob/master/piltover/server.py"
        
        TL["TL Serialization (JIT)"]:::core
        click TL "https://github.com/DavideGalilei/piltover/blob/master/piltover/tl/tl.py"
        
        MH["Message Handlers"]
        US["Update System"]
        SM["Session Management"]
        
        subgraph "TL Schemas"
            direction TB
            AS["API Schema"]
            click AS "https://github.com/DavideGalilei/piltover/blob/master/piltover/tl/generated/api_tl.py"
            MP["MTProto Schema"]
            click MP "https://github.com/DavideGalilei/piltover/blob/master/piltover/tl/generated/mtproto_tl.py"
        end
    end

    subgraph "Storage Layer"
        direction TB
        AKS["Auth Keys Storage"]:::planned
        MS2["Message Storage"]:::planned
        UD["User Data Storage"]:::planned
        UP["Updates Storage"]:::planned
    end

    TC & WK & WZ --> WP
    PG & TN --> CH
    WP --> CH
    CH --> BS
    BS --> AB & IM & PI & TF & OB
    AB & IM & PI & TF & OB --> MT
    MT --> AK
    AK --> RS
    RS --> MS
    MS --> SV
    SV --> TL
    TL --> MH & US & SM
    MH & US & SM --> AKS & MS2 & UD & UP

    classDef core fill:#2374ab
    classDef proxy fill:#47a025
    classDef security fill:#f7d794
    classDef planned fill:#95afc0,stroke-dasharray: 5 5
    
    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Proxy Components"]:::proxy
        L3["Security Components"]:::security
        L4["Planned Features"]:::planned
    end

    %% Notes
    note["Note: This is an experimental implementation"]
    style note fill:#ffeb95,stroke:#f7d794
```
