de-par/mtp-manager

Purpose and Entry Points

mtp-manager is a Python 3.11+ Textual terminal application for provisioning and operating a telemt MTProto/Fake-TLS proxy on systemd Linux hosts. It performs privileged host changes: package installation, filesystem writes, firewall updates, and service/timer management.

The CLI entrypoint and internal service-command dispatch live in src/app.py. Startup assembles dependencies and applies compatibility/migration glue in src/bootstrap.py; user-facing actions pass through src/controller.py.

Composition Root and Control Boundary

src/bootstrap.py is the composition root: it connects domain services, infrastructure adapters, localization, and the selected UI backend. src/controller.py is the application-facing orchestration layer used by the TUI rather than allowing UI code to directly issue host operations.

The infrastructure boundary is explicit under src/infra/: system interaction is routed through src/infra/shell.py, while durable managed state is handled through src/infra/storage.py. This concentrates privileged commands and atomic generated-file writes outside UI and service logic.

Terminal UI and Interaction Flow

The primary runtime is a Textual TUI, orchestrated by src/ui/textual_app.py. It renders the operational dashboard and metrics via src/ui/dashboard.py, maintains interactive UI state in src/ui/state.py, and uses modal workflows from src/ui/modals.py and src/ui/modal_flow.py.

src/ui/backend.py provides the UI-backend abstraction consumed by the entrypoint, separating application startup from the concrete Textual presentation. UI labels and user feedback are localized through src/i18n/catalog.py with English, Russian, and Chinese catalogs (src/i18n/en.py, src/i18n/ru.py, src/i18n/zh.py).

Proxy Installation and Runtime Management

Installation/update orchestration is implemented by src/services/install_service.py; source/tag/commit selection is handled by src/services/source_service.py. These services install and maintain the external telemt binary under /opt/telemt, using distribution-aware package operations in src/infra/distro.py and src/infra/packages.py.

Runtime configuration and proxy process concerns are separated into src/services/proxy_runtime_service.py and src/services/settings_service.py. Typed configuration, secret, export, and health contracts live in src/models/settings.py, src/models/secret.py, src/models/export.py, and src/models/health.py.

System Integration and Scheduled Operations

src/services/systemd_service.py manages telemt.service plus managed refresh and cleanup units/timers. The systemd adapter is src/infra/systemd.py; generated units invoke the installed mtp-manager command, enabling scheduled/internal commands to reuse application logic.

Network-facing host changes are isolated in src/services/network_service.py, backed by src/infra/firewall.py and src/infra/public_ip.py. This is the boundary for firewall rules and public-address discovery rather than a network proxy implementation inside this repository.

Operations, Diagnostics, and Persistent State

Operational workflows are divided into focused services: inventory and user/secret views in src/services/inventory_service.py, health/status/log inspection in src/services/diagnostics_service.py, connection-link production in src/services/export_service.py, and cleanup of logs, cache, and runtime artifacts in src/services/cleanup_service.py.

Managed host state spans /etc/mtp-manager configuration, /var/lib/mtp-manager application data, /opt/telemt, and systemd unit paths. Older mtproxy layouts are accounted for during bootstrap/migration, keeping legacy conversion outside normal TUI flows.