# de-par/mtp-manager architecture

> Architecture diagram of the GitHub repository de-par/mtp-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/de-par/mtp-manager
- Repository: https://github.com/de-par/mtp-manager

## Overview

#### 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.

Main entry points: [`src/controller.py`](https://github.com/de-par/mtp-manager/blob/main/src/controller.py) (Application controller), [`src/services/install_service.py`](https://github.com/de-par/mtp-manager/blob/main/src/services/install_service.py) (Install & source management), [`src/services/systemd_service.py`](https://github.com/de-par/mtp-manager/blob/main/src/services/systemd_service.py) (Systemd management), [`src/infra/shell.py`](https://github.com/de-par/mtp-manager/blob/main/src/infra/shell.py) (Shell execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & application"]
  node_app["CLI entrypoint<br/>Python CLI<br/>[app.py]"]
  node_bootstrap["Composition root<br/>dependency assembly<br/>[bootstrap.py]"]
  node_controller["Application controller<br/>orchestration<br/>[controller.py]"]
end

subgraph group_ui["Terminal UI"]
  node_ui_backend{{"UI backend abstraction<br/>presentation port<br/>[backend.py]"}}
  node_textual_app["Textual application<br/>terminal UI<br/>[textual_app.py]"]
  node_dashboard_flow["Dashboard &amp; modal flows<br/>UI workflows<br/>[dashboard.py]"]
  node_i18n["Localization catalogs<br/>i18n<br/>[catalog.py]"]
end

subgraph group_services["Operational services"]
  node_install["Install &amp; source management<br/>provisioning service<br/>[install_service.py]"]
  node_runtime_settings["Proxy runtime &amp; settings<br/>runtime service"]
  node_systemd_service["Systemd management<br/>system service<br/>[systemd_service.py]"]
  node_network_service["Network management<br/>network service<br/>[network_service.py]"]
  node_operations["Operations &amp; diagnostics<br/>operational services"]
  node_contracts["Settings &amp; operational contracts<br/>typed models<br/>[settings.py]"]
end

subgraph group_infra["Host integration"]
  node_shell{{"Shell execution<br/>privileged command adapter<br/>[shell.py]"}}
  node_storage[("Managed storage<br/>persistence adapter<br/>[storage.py]")]
  node_package_stack{{"Distro &amp; package adapters<br/>package integration<br/>[distro.py]"}}
  node_systemd_adapter{{"Systemd adapter<br/>systemd integration<br/>[systemd.py]"}}
  node_network_adapters{{"Firewall &amp; public-IP adapters<br/>network integration<br/>[firewall.py]"}}
  node_managed_host[("Managed host state<br/>Linux host resources")]
  node_telemt["telemt proxy<br/>external MTProto proxy"]
end

node_app -->|"initializes"| node_bootstrap
node_app -->|"dispatches commands"| node_controller
node_bootstrap -->|"assembles"| node_controller
node_bootstrap -->|"selects"| node_ui_backend
node_ui_backend -->|"implements"| node_textual_app
node_textual_app -->|"renders and drives"| node_dashboard_flow
node_textual_app -->|"localizes UI"| node_i18n
node_dashboard_flow -->|"user actions"| node_controller
node_controller -->|"provisions"| node_install
node_controller -->|"configures"| node_runtime_settings
node_controller -->|"manages units"| node_systemd_service
node_controller -->|"changes network"| node_network_service
node_controller -->|"runs workflows"| node_operations
node_runtime_settings -->|"uses"| node_contracts
node_install -->|"installs dependencies"| node_package_stack
node_install -->|"executes provisioning"| node_shell
node_install -->|"installs or updates"| node_telemt
node_runtime_settings -->|"persists configuration"| node_storage
node_systemd_service -->|"controls"| node_systemd_adapter
node_systemd_service -->|"writes units and timers"| node_managed_host
node_systemd_adapter -->|"executes systemctl"| node_shell
node_network_service -->|"uses"| node_network_adapters
node_network_adapters -->|"applies host changes"| node_shell
node_storage -->|"writes durable state"| node_managed_host
node_operations -->|"inspects and cleans"| node_shell
node_managed_host -->|"hosts installation"| node_telemt
node_systemd_service -.->|"scheduled units invoke"| node_app

click node_app "https://github.com/de-par/mtp-manager/blob/main/src/app.py"
click node_bootstrap "https://github.com/de-par/mtp-manager/blob/main/src/bootstrap.py"
click node_controller "https://github.com/de-par/mtp-manager/blob/main/src/controller.py"
click node_ui_backend "https://github.com/de-par/mtp-manager/blob/main/src/ui/backend.py"
click node_textual_app "https://github.com/de-par/mtp-manager/blob/main/src/ui/textual_app.py"
click node_dashboard_flow "https://github.com/de-par/mtp-manager/blob/main/src/ui/dashboard.py"
click node_i18n "https://github.com/de-par/mtp-manager/blob/main/src/i18n/catalog.py"
click node_install "https://github.com/de-par/mtp-manager/blob/main/src/services/install_service.py"
click node_runtime_settings "https://github.com/de-par/mtp-manager/blob/main/src/services/proxy_runtime_service.py"
click node_systemd_service "https://github.com/de-par/mtp-manager/blob/main/src/services/systemd_service.py"
click node_network_service "https://github.com/de-par/mtp-manager/blob/main/src/services/network_service.py"
click node_operations "https://github.com/de-par/mtp-manager/blob/main/src/services/diagnostics_service.py"
click node_contracts "https://github.com/de-par/mtp-manager/blob/main/src/models/settings.py"
click node_shell "https://github.com/de-par/mtp-manager/blob/main/src/infra/shell.py"
click node_storage "https://github.com/de-par/mtp-manager/blob/main/src/infra/storage.py"
click node_package_stack "https://github.com/de-par/mtp-manager/blob/main/src/infra/distro.py"
click node_systemd_adapter "https://github.com/de-par/mtp-manager/blob/main/src/infra/systemd.py"
click node_network_adapters "https://github.com/de-par/mtp-manager/blob/main/src/infra/firewall.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_app,node_bootstrap,node_controller toneBlue
class node_ui_backend,node_textual_app,node_dashboard_flow,node_i18n toneAmber
class node_install,node_runtime_settings,node_systemd_service,node_network_service,node_operations,node_contracts toneMint
class node_shell,node_storage,node_package_stack,node_systemd_adapter,node_network_adapters,node_managed_host,node_telemt toneRose
```

## Components

### Entry & application

- [CLI entrypoint](https://github.com/de-par/mtp-manager/blob/main/src/app.py): Python CLI · Dispatches interactive and scheduled internal commands. · `src/app.py`
- [Composition root](https://github.com/de-par/mtp-manager/blob/main/src/bootstrap.py): dependency assembly · Wires services, adapters, localization, UI backend, and legacy migration. · `src/bootstrap.py`
- [Application controller](https://github.com/de-par/mtp-manager/blob/main/src/controller.py): orchestration · Control boundary between UI actions and host operations. · `src/controller.py`

### Terminal UI

- [UI backend abstraction](https://github.com/de-par/mtp-manager/blob/main/src/ui/backend.py): presentation port · `src/ui/backend.py`
- [Textual application](https://github.com/de-par/mtp-manager/blob/main/src/ui/textual_app.py): terminal UI · Primary interactive operational runtime. · `src/ui/textual_app.py`
- [Dashboard & modal flows](https://github.com/de-par/mtp-manager/blob/main/src/ui/dashboard.py): UI workflows · Dashboard, interactive state, and modal workflows. · `src/ui/dashboard.py`
- [Localization catalogs](https://github.com/de-par/mtp-manager/blob/main/src/i18n/catalog.py): i18n · English, Russian, and Chinese UI text. · `src/i18n/catalog.py`

### Operational services

- [Install & source management](https://github.com/de-par/mtp-manager/blob/main/src/services/install_service.py): provisioning service · Selects telemt source and installs or updates it under /opt/telemt. · `src/services/install_service.py`
- [Proxy runtime & settings](https://github.com/de-par/mtp-manager/blob/main/src/services/proxy_runtime_service.py): runtime service · Manages proxy configuration and runtime concerns. · `src/services/proxy_runtime_service.py`
- [Systemd management](https://github.com/de-par/mtp-manager/blob/main/src/services/systemd_service.py): system service · Manages telemt and refresh/cleanup units and timers. · `src/services/systemd_service.py`
- [Network management](https://github.com/de-par/mtp-manager/blob/main/src/services/network_service.py): network service · Applies firewall rules and discovers public addresses. · `src/services/network_service.py`
- [Operations & diagnostics](https://github.com/de-par/mtp-manager/blob/main/src/services/diagnostics_service.py): operational services · Inventory, health, logs, exports, and cleanup workflows. · `src/services/diagnostics_service.py`
- [Settings & operational contracts](https://github.com/de-par/mtp-manager/blob/main/src/models/settings.py): typed models · Configuration, secrets, exports, and health contracts. · `src/models/settings.py`

### Host integration

Privileged host operations and managed persistence.

- [Shell execution](https://github.com/de-par/mtp-manager/blob/main/src/infra/shell.py): privileged command adapter · Central route for host command execution. · `src/infra/shell.py`
- [Managed storage](https://github.com/de-par/mtp-manager/blob/main/src/infra/storage.py): persistence adapter · Atomically writes generated files and durable managed state. · `src/infra/storage.py`
- [Distro & package adapters](https://github.com/de-par/mtp-manager/blob/main/src/infra/distro.py): package integration · Distribution-aware package operations. · `src/infra/distro.py`
- [Systemd adapter](https://github.com/de-par/mtp-manager/blob/main/src/infra/systemd.py): systemd integration · `src/infra/systemd.py`
- [Firewall & public-IP adapters](https://github.com/de-par/mtp-manager/blob/main/src/infra/firewall.py): network integration · `src/infra/firewall.py`
- **Managed host state**: Linux host resources · Configuration, application data, telemt install, firewall, and systemd units.
- **telemt proxy**: external MTProto proxy · Installed external Fake-TLS proxy binary.

## Connections

- CLI entrypoint → Composition root: initializes
- CLI entrypoint → Application controller: dispatches commands
- Composition root → Application controller: assembles
- Composition root → UI backend abstraction: selects
- UI backend abstraction → Textual application: implements
- Textual application → Dashboard & modal flows: renders and drives
- Textual application → Localization catalogs: localizes UI
- Dashboard & modal flows → Application controller: user actions
- Application controller → Install & source management: provisions
- Application controller → Proxy runtime & settings: configures
- Application controller → Systemd management: manages units
- Application controller → Network management: changes network
- Application controller → Operations & diagnostics: runs workflows
- Proxy runtime & settings → Settings & operational contracts: uses
- Install & source management → Distro & package adapters: installs dependencies
- Install & source management → Shell execution: executes provisioning
- Install & source management → telemt proxy: installs or updates
- Proxy runtime & settings → Managed storage: persists configuration
- Systemd management → Systemd adapter: controls
- Systemd management → Managed host state: writes units and timers
- Systemd adapter → Shell execution: executes systemctl
- Network management → Firewall & public-IP adapters: uses
- Firewall & public-IP adapters → Shell execution: applies host changes
- Managed storage → Managed host state: writes durable state
- Operations & diagnostics → Shell execution: inspects and cleans
- Managed host state → telemt proxy: hosts installation
- Systemd management → CLI entrypoint: scheduled units invoke