# am1rtl/ambox architecture

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

- Interactive diagram: https://gitdiagram.com/am1rtl/ambox
- Repository: https://github.com/am1rtl/ambox

## Overview

#### Назначение и запуск
`ambox` — Linux desktop-клиент для импорта sing-box/NekoBox VPN-профилей, управления локальным `sing-box` и отображения статуса подключения. Точки запуска: `main.py` и `__main__.py`; основное GUI-приложение собирается вокруг главного окна в `app/main_window.py`.

#### GUI и пользовательский поток
Главный интерфейс управляет импортом/выбором профиля, routing/DNS-настройками, подключением, логами, latency и traffic statistics. Центральный UI-компонент — `app/main_window.py`; краткие пользовательские уведомления выделены в `app/toast.py`. UI передаёт выбранный профиль и параметры подключения менеджеру VPN, а результаты процесса и измерений возвращаются в окно.

#### Профили и разбор конфигураций
Импортируются sing-box JSON и ссылки VMess, VLESS, Trojan, Shadowsocks, HTTP и SOCKS. Парсинг и нормализация входных форматов сосредоточены в `app/config_parser.py`. Результатом является профиль/конфигурация, пригодные для сохранения и генерации активной sing-box-конфигурации; постоянные профили хранятся в `~/.ambox/profiles.json`.

#### Управление sing-box
`app/vpn_manager.py` образует границу между приложением и системным VPN-движком: подготавливает активную конфигурацию, запускает/останавливает `sing-box run -c <config>`, получает состояние и логи процесса. Активный конфиг располагается в `~/.ambox/active-config.json`; для TUN-режима внешний бинарник `sing-box` должен быть в `PATH` и обычно требует `CAP_NET_ADMIN`. Установка из UI использует системные привилегии через `pkexec` и APT/SagerNet.

#### Routing и DNS как конфигурационная граница
Настройки интерфейса преобразуются в sing-box-правила: проксирование всего трафика, доменных списков либо исключений; отдельно поддерживаются обход `.ru`, поддомены и DNS через прокси/напрямую/custom server. Проверка и формирование этих параметров относятся к жизненному циклу подключения в `app/vpn_manager.py`, а их разбор и сохранение настроек — к `app/config_parser.py` и `app/app_paths.py`.

#### Latency, автопереключение и статистика
`app/latency.py` измеряет доступность профилей TCP-подключением к их endpoint с пользовательским timeout. Эти результаты питают UI и режим автоматического выбора минимальной задержки перед/во время использования профилей. Накопительная traffic statistics и UI/routing/DNS-параметры сохраняются в `~/.ambox/settings.ini`.

#### Локальное состояние, логирование и поставка
`app/app_paths.py` централизует расположение пользовательского состояния под `~/.ambox`: настройки, профили, active config, `cache.db`, application log и папку ручного импорта. `build_linux.sh` упаковывает приложение как одиночный Linux ELF через PyInstaller; зависимости Python определены в `requirements.txt`. Debug-флаг `-d` включает более подробные логи и traceback.

Main entry points: [`app/main_window.py`](https://github.com/am1rtl/ambox/blob/main/app/main_window.py) (Main window), [`app/vpn_manager.py`](https://github.com/am1rtl/ambox/blob/main/app/vpn_manager.py) (VPN manager), [`app/app_paths.py`](https://github.com/am1rtl/ambox/blob/main/app/app_paths.py) (App paths & settings), [`app/config_parser.py`](https://github.com/am1rtl/ambox/blob/main/app/config_parser.py) (Config parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gui["Desktop UI"]
  node_main_window["Main window<br/>GUI controller<br/>[main_window.py]"]
  node_toast["Toast notifications<br/>GUI feedback<br/>[toast.py]"]
end

subgraph group_core["Connection core"]
  node_parser["Config parser<br/>profile parser<br/>[config_parser.py]"]
  node_vpn_manager["VPN manager<br/>sing-box lifecycle<br/>[vpn_manager.py]"]
  node_sing_box{{"sing-box engine<br/>external binary"}}
  node_latency["Latency checker<br/>endpoint probe<br/>[latency.py]"]
end

subgraph group_state["Local state"]
  node_paths["App paths &amp; settings<br/>state access<br/>[app_paths.py]"]
  node_profiles[("Saved profiles<br/>profile store")]
  node_settings[("Settings &amp; traffic stats<br/>settings store")]
  node_active_config["Active sing-box config<br/>generated config"]
  node_runtime_state[("Cache, logs &amp; imports<br/>runtime files")]
end

subgraph group_delivery["Delivery"]
  node_packaging["Linux package build<br/>PyInstaller build<br/>[build_linux.sh]"]
  node_dependencies["Python dependencies<br/>requirements<br/>[requirements.txt]"]
end

node_entry["CLI entry points<br/>Python entry<br/>[main.py]"]

node_entry -->|"launches"| node_main_window
node_main_window -->|"imports profiles"| node_parser
node_parser -->|"saves normalized profiles"| node_profiles
node_main_window -->|"selects profile"| node_profiles
node_main_window -->|"loads and saves preferences"| node_paths
node_paths -->|"persists"| node_settings
node_paths -->|"locates"| node_runtime_state
node_main_window -->|"connect, disconnect, routing and DNS"| node_vpn_manager
node_vpn_manager -->|"generates"| node_active_config
node_vpn_manager -->|"starts and monitors"| node_sing_box
node_vpn_manager -->|"status and process logs"| node_main_window
node_main_window -->|"requests measurements"| node_latency
node_latency -->|"latency and auto-select result"| node_main_window
node_main_window -->|"shows brief feedback"| node_toast
node_dependencies -->|"supplies build dependencies"| node_packaging
node_packaging -.->|"packages application"| node_entry

click node_entry "https://github.com/am1rtl/ambox/blob/main/main.py"
click node_main_window "https://github.com/am1rtl/ambox/blob/main/app/main_window.py"
click node_toast "https://github.com/am1rtl/ambox/blob/main/app/toast.py"
click node_parser "https://github.com/am1rtl/ambox/blob/main/app/config_parser.py"
click node_paths "https://github.com/am1rtl/ambox/blob/main/app/app_paths.py"
click node_vpn_manager "https://github.com/am1rtl/ambox/blob/main/app/vpn_manager.py"
click node_latency "https://github.com/am1rtl/ambox/blob/main/app/latency.py"
click node_packaging "https://github.com/am1rtl/ambox/blob/main/build_linux.sh"
click node_dependencies "https://github.com/am1rtl/ambox/blob/main/requirements.txt"

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_main_window,node_toast toneBlue
class node_parser,node_vpn_manager,node_sing_box,node_latency toneAmber
class node_paths,node_profiles,node_settings,node_active_config,node_runtime_state toneMint
class node_packaging,node_dependencies toneRose
class node_entry toneNeutral
```

## Components

### Desktop UI

- [Main window](https://github.com/am1rtl/ambox/blob/main/app/main_window.py): GUI controller · Coordinates profiles, connection controls, settings, logs, latency, and traffic UI. · `app/main_window.py`
- [Toast notifications](https://github.com/am1rtl/ambox/blob/main/app/toast.py): GUI feedback · `app/toast.py`

### Connection core

- [Config parser](https://github.com/am1rtl/ambox/blob/main/app/config_parser.py): profile parser · Imports and normalizes sing-box JSON and supported VPN links. · `app/config_parser.py`
- [VPN manager](https://github.com/am1rtl/ambox/blob/main/app/vpn_manager.py): sing-box lifecycle · Builds active configuration and controls the local sing-box process. · `app/vpn_manager.py`
- **sing-box engine**: external binary · Runs the generated configuration; TUN mode needs CAP_NET_ADMIN.
- [Latency checker](https://github.com/am1rtl/ambox/blob/main/app/latency.py): endpoint probe · TCP-probes profile endpoints for UI display and automatic profile selection. · `app/latency.py`

### Local state

- [App paths & settings](https://github.com/am1rtl/ambox/blob/main/app/app_paths.py): state access · Centralizes state locations and persists UI, routing, DNS, and statistics settings. · `app/app_paths.py`
- **Saved profiles**: profile store
- **Settings & traffic stats**: settings store
- **Active sing-box config**: generated config
- **Cache, logs & imports**: runtime files · Includes cache.db, application log, and manual-import directory.

### Delivery

- [Linux package build](https://github.com/am1rtl/ambox/blob/main/build_linux.sh): PyInstaller build · Builds a single Linux ELF application. · `build_linux.sh`
- [Python dependencies](https://github.com/am1rtl/ambox/blob/main/requirements.txt): requirements · `requirements.txt`

### Other components

- [CLI entry points](https://github.com/am1rtl/ambox/blob/main/main.py): Python entry · Starts the desktop client and enables debug mode. · `main.py`

## Connections

- CLI entry points → Main window: launches
- Main window → Config parser: imports profiles
- Config parser → Saved profiles: saves normalized profiles
- Main window → Saved profiles: selects profile
- Main window → App paths & settings: loads and saves preferences
- App paths & settings → Settings & traffic stats: persists
- App paths & settings → Cache, logs & imports: locates
- Main window → VPN manager: connect, disconnect, routing and DNS
- VPN manager → Active sing-box config: generates
- VPN manager → sing-box engine: starts and monitors
- VPN manager → Main window: status and process logs
- Main window → Latency checker: requests measurements
- Latency checker → Main window: latency and auto-select result
- Main window → Toast notifications: shows brief feedback
- Python dependencies → Linux package build: supplies build dependencies
- Linux package build → CLI entry points: packages application