# rootmax84/pytgw architecture

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

- Interactive diagram: https://gitdiagram.com/rootmax84/pytgw
- Repository: https://github.com/rootmax84/pytgw

## Overview

PYTGW is a Python Telegram Bot API reverse proxy. Clients send Bot API requests to its FastAPI routes; the gateway parses the token and method, forwards the request to Telegram, and returns the upstream response. The main runtime also provides health checks, request safeguards, configurable outbound connections, retries, and token-masked logging. The repository has one substantial source file, so these responsibilities share its path. Some features are documented in the README but their implementation details are not shown in the excerpts.

Main entry points: [`app/main.py`](https://github.com/rootmax84/pytgw/blob/main/app/main.py) (Request handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Gateway entry"]
  node_routes["HTTP routes<br/>[main.py]"]
  node_health["Health check<br/>[main.py]"]
  node_request_handler["Request handler<br/>[main.py]"]
end

subgraph group_security["Request safeguards"]
  node_trusted_proxy["Trusted proxy handling<br/>[main.py]"]
  node_connection_guard["Connection ID guard<br/>[main.py]"]
  node_body_limit["Body size limit<br/>[main.py]"]
end

subgraph group_proxy["Proxy runtime"]
  node_token_parser["Token and method parsing<br/>[main.py]"]
  node_payload_forwarder["Payload forwarding<br/>[main.py]"]
  node_http_client["Async HTTP client<br/>[main.py]"]
  node_logging["Masked logging<br/>[main.py]"]
end

node_client(("Bot API client"))
node_telegram["Telegram Bot API"]
node_socks["SOCKS5 proxy"]

node_client -->|"sends requests"| node_routes
node_routes -->|"serves health"| node_health
node_routes -->|"dispatches to"| node_request_handler
node_request_handler -->|"parses path"| node_token_parser
node_request_handler -->|"forwards request"| node_payload_forwarder
node_payload_forwarder -->|"sends request"| node_http_client
node_http_client -->|"proxies Bot API"| node_telegram
node_http_client -.->|"routes optionally"| node_socks
node_request_handler -->|"masks tokens"| node_logging

click node_routes "https://github.com/rootmax84/pytgw/blob/main/app/main.py"
click node_health "https://github.com/rootmax84/pytgw/blob/main/app/main.py"
click node_request_handler "https://github.com/rootmax84/pytgw/blob/main/app/main.py"
click node_trusted_proxy "https://github.com/rootmax84/pytgw/blob/main/app/main.py"
click node_connection_guard "https://github.com/rootmax84/pytgw/blob/main/app/main.py"
click node_body_limit "https://github.com/rootmax84/pytgw/blob/main/app/main.py"
click node_token_parser "https://github.com/rootmax84/pytgw/blob/main/app/main.py"
click node_payload_forwarder "https://github.com/rootmax84/pytgw/blob/main/app/main.py"
click node_http_client "https://github.com/rootmax84/pytgw/blob/main/app/main.py"
click node_logging "https://github.com/rootmax84/pytgw/blob/main/app/main.py"

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_routes,node_health,node_request_handler,node_client toneBlue
class node_trusted_proxy,node_connection_guard,node_body_limit toneAmber
class node_token_parser,node_payload_forwarder,node_http_client,node_logging,node_telegram toneMint
class node_socks toneIndigo
```

## Components

### Gateway entry

- [HTTP routes](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`
- [Health check](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`
- [Request handler](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`

### Request safeguards

- [Trusted proxy handling](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`
- [Connection ID guard](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`
- [Body size limit](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`

### Proxy runtime

- [Token and method parsing](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`
- [Payload forwarding](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`
- [Async HTTP client](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`
- [Masked logging](https://github.com/rootmax84/pytgw/blob/main/app/main.py): `app/main.py`

### Other components

- **Bot API client**
- **Telegram Bot API**
- **SOCKS5 proxy**

## Connections

- Bot API client → HTTP routes: sends requests (evidence: `README.md`)
- HTTP routes → Health check: serves health (evidence: `app/main.py`)
- HTTP routes → Request handler: dispatches to (evidence: `app/main.py`)
- Request handler → Token and method parsing: parses path (evidence: `app/main.py`)
- Request handler → Payload forwarding: forwards request (evidence: `app/main.py`)
- Payload forwarding → Async HTTP client: sends request (evidence: `app/main.py`)
- Async HTTP client → Telegram Bot API: proxies Bot API (evidence: `README.md`)
- Async HTTP client → SOCKS5 proxy: routes optionally (evidence: `README.md`)
- Request handler → Masked logging: masks tokens (evidence: `README.md`)
