# immaghzbad/aetherst architecture

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

- Interactive diagram: https://gitdiagram.com/immaghzbad/aetherst
- Repository: https://github.com/immaghzbad/aetherst

## Overview

AetherST is a cross-platform VPN/proxy client for Android and Windows. Users configure a transport and routing options, start a connection, and receive tunneled or proxied traffic; optional Psiphon and Tor chains add another routing layer. Android’s connection controller coordinates the VPN service and tunnel engines, while shared Compose UI and configuration support platform-specific controls. The README documents transport and scanning capabilities beyond the sampled implementation; those are represented at subsystem level. Arrows are limited to cited source references or documented behavior.

Main entry points: [`app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt`](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt) (VPN Service), [`app/src/main/java/io/github/immaghzbad/aetherst/core/ConnectionController.kt`](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/ConnectionController.kt) (Android Controller), [`composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/App.kt`](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/App.kt) (Shared UI), [`composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/AetherConfigRepository.kt`](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/AetherConfigRepository.kt) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_android_app["Android App<br/>[MainActivity.kt]"]
  node_shared_ui["Shared UI<br/>[App.kt]"]
  node_desktop_entry["Desktop Entry<br/>[main.kt]"]
end

subgraph group_connection["Connection Orchestration"]
  node_android_control["Android Controller"]
  node_vpn_service["VPN Service"]
  node_desktop_control["Desktop Controller"]
end

subgraph group_transport["Tunnel and Routing"]
  node_aether_core["Aether Core"]
  node_gateway_scan["Gateway Scanning"]
  node_cloak["Cloak Transport<br/>[CloakController.kt]"]
  node_routing["Traffic Routing<br/>[RoutingEngine.kt]"]
  node_hev["HEV Tunnel Engine"]
  node_socks_bridge["SOCKS/TUN Bridge<br/>[SocksTunBridge.kt]"]
end

subgraph group_chains["Optional Chains"]
  node_psiphon["Psiphon Chain"]
  node_tor["Tor Chain<br/>[TorController.kt]"]
end

subgraph group_insight["Configuration and Diagnostics"]
  node_config[("Configuration")]
  node_config_model["Config Model<br/>[AetherConfig.kt]"]
  node_ip_info["IP Lookup"]
  node_logs[("Log Repository<br/>[LogRepository.kt]")]
  node_diagnostics["Diagnostics"]
end

node_user(("User"))
node_internet(("Network / Gateways"))

node_user -->|"opens"| node_android_app
node_android_app -->|"hosts"| node_shared_ui
node_user -.->|"launches"| node_desktop_entry
node_desktop_entry -->|"starts UI"| node_shared_ui
node_shared_ui -.->|"reads settings"| node_config
node_config -->|"loads"| node_config_model
node_android_control -->|"reads config"| node_config
node_android_control -->|"coordinates"| node_vpn_service
node_desktop_control -->|"reads config"| node_config
node_android_control -.->|"starts core"| node_aether_core
node_aether_core -->|"scans gateways"| node_gateway_scan
node_gateway_scan -->|"checks gateways"| node_internet
node_android_control -->|"starts transport"| node_cloak
node_vpn_service -->|"configures routing"| node_routing
node_vpn_service -->|"starts engine"| node_hev
node_vpn_service -->|"manages bridge"| node_socks_bridge
node_vpn_service -->|"starts chain"| node_psiphon
node_vpn_service -->|"starts chain"| node_tor
node_psiphon -->|"routes egress"| node_internet
node_tor -->|"routes egress"| node_internet
node_android_control -->|"records events"| node_logs
node_hev -->|"writes logs"| node_logs
node_shared_ui -.->|"shows lookup"| node_ip_info
node_shared_ui -.->|"offers tests"| node_diagnostics

click node_android_app "https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/MainActivity.kt"
click node_shared_ui "https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/App.kt"
click node_desktop_entry "https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/desktopMain/kotlin/io/github/immaghzbad/aetherst/main.kt"
click node_config "https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/AetherConfigRepository.kt"
click node_config_model "https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/model/AetherConfig.kt"
click node_android_control "https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/ConnectionController.kt"
click node_vpn_service "https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt"
click node_desktop_control "https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/desktopMain/kotlin/io/github/immaghzbad/aetherst/core/ConnectionController.kt"
click node_aether_core "https://github.com/immaghzbad/aetherst/tree/main/app/src/main/java/io/github/immaghzbad/aetherst/core"
click node_gateway_scan "https://github.com/immaghzbad/aetherst/tree/main/app/src/main/java/io/github/immaghzbad/aetherst/core"
click node_cloak "https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/CloakController.kt"
click node_routing "https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/RoutingEngine.kt"
click node_hev "https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/HevTun2SocksEngine.kt"
click node_socks_bridge "https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/SocksTunBridge.kt"
click node_psiphon "https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/PsiphonController.kt"
click node_tor "https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/TorController.kt"
click node_ip_info "https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/IpInfoRepository.kt"
click node_logs "https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/LogRepository.kt"
click node_diagnostics "https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/DnsBenchmarkRepository.kt"

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_android_app,node_shared_ui,node_desktop_entry,node_user toneBlue
class node_android_control,node_vpn_service,node_desktop_control toneAmber
class node_aether_core,node_gateway_scan,node_cloak,node_routing,node_hev,node_socks_bridge toneMint
class node_psiphon,node_tor toneRose
class node_config,node_config_model,node_ip_info,node_logs,node_diagnostics,node_internet toneIndigo
```

## Components

### User Interface

- [Android App](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/MainActivity.kt): `app/src/main/java/io/github/immaghzbad/aetherst/MainActivity.kt`
- [Shared UI](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/App.kt): `composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/App.kt`
- [Desktop Entry](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/desktopMain/kotlin/io/github/immaghzbad/aetherst/main.kt): `composeApp/src/desktopMain/kotlin/io/github/immaghzbad/aetherst/main.kt`

### Connection Orchestration

- [Android Controller](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/ConnectionController.kt): `app/src/main/java/io/github/immaghzbad/aetherst/core/ConnectionController.kt`
- [VPN Service](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt): `app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt`
- [Desktop Controller](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/desktopMain/kotlin/io/github/immaghzbad/aetherst/core/ConnectionController.kt): `composeApp/src/desktopMain/kotlin/io/github/immaghzbad/aetherst/core/ConnectionController.kt`

### Tunnel and Routing

- [Aether Core](https://github.com/immaghzbad/aetherst/tree/main/app/src/main/java/io/github/immaghzbad/aetherst/core): `app/src/main/java/io/github/immaghzbad/aetherst/core`
- [Gateway Scanning](https://github.com/immaghzbad/aetherst/tree/main/app/src/main/java/io/github/immaghzbad/aetherst/core): `app/src/main/java/io/github/immaghzbad/aetherst/core`
- [Cloak Transport](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/CloakController.kt): `app/src/main/java/io/github/immaghzbad/aetherst/core/CloakController.kt`
- [Traffic Routing](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/RoutingEngine.kt): `app/src/main/java/io/github/immaghzbad/aetherst/core/RoutingEngine.kt`
- [HEV Tunnel Engine](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/HevTun2SocksEngine.kt): `app/src/main/java/io/github/immaghzbad/aetherst/core/HevTun2SocksEngine.kt`
- [SOCKS/TUN Bridge](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/SocksTunBridge.kt): `app/src/main/java/io/github/immaghzbad/aetherst/core/SocksTunBridge.kt`

### Optional Chains

- [Psiphon Chain](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/PsiphonController.kt): `app/src/main/java/io/github/immaghzbad/aetherst/core/PsiphonController.kt`
- [Tor Chain](https://github.com/immaghzbad/aetherst/blob/main/app/src/main/java/io/github/immaghzbad/aetherst/core/TorController.kt): `app/src/main/java/io/github/immaghzbad/aetherst/core/TorController.kt`

### Configuration and Diagnostics

- [Configuration](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/AetherConfigRepository.kt): `composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/AetherConfigRepository.kt`
- [Config Model](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/model/AetherConfig.kt): `composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/model/AetherConfig.kt`
- [IP Lookup](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/IpInfoRepository.kt): `composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/IpInfoRepository.kt`
- [Log Repository](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/LogRepository.kt): `composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/LogRepository.kt`
- [Diagnostics](https://github.com/immaghzbad/aetherst/blob/main/composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/DnsBenchmarkRepository.kt): `composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/DnsBenchmarkRepository.kt`

### Other components

- **User**
- **Network / Gateways**

## Connections

- User → Android App: opens (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/MainActivity.kt`)
- Android App → Shared UI: hosts (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/MainActivity.kt`)
- User → Desktop Entry: launches (evidence: `README.md`)
- Desktop Entry → Shared UI: starts UI (evidence: `composeApp/src/desktopMain/kotlin/io/github/immaghzbad/aetherst/main.kt`)
- Shared UI → Configuration: reads settings (evidence: `composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/App.kt`)
- Configuration → Config Model: loads (evidence: `composeApp/src/commonMain/kotlin/io/github/immaghzbad/aetherst/shared/data/AetherConfigRepository.kt`)
- Android Controller → Configuration: reads config (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/core/ConnectionController.kt`)
- Android Controller → VPN Service: coordinates (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/core/ConnectionController.kt`)
- Desktop Controller → Configuration: reads config (evidence: `composeApp/src/desktopMain/kotlin/io/github/immaghzbad/aetherst/core/ConnectionController.kt`)
- Android Controller → Aether Core: starts core (evidence: `README.md`)
- Aether Core → Gateway Scanning: scans gateways (evidence: `README.md`)
- Gateway Scanning → Network / Gateways: checks gateways (evidence: `README.md`)
- Android Controller → Cloak Transport: starts transport (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/core/ConnectionController.kt`)
- VPN Service → Traffic Routing: configures routing (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt`)
- VPN Service → HEV Tunnel Engine: starts engine (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt`)
- VPN Service → SOCKS/TUN Bridge: manages bridge (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt`)
- VPN Service → Psiphon Chain: starts chain (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt`)
- VPN Service → Tor Chain: starts chain (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/service/AetherVpnService.kt`)
- Psiphon Chain → Network / Gateways: routes egress (evidence: `README.md`)
- Tor Chain → Network / Gateways: routes egress (evidence: `README.md`)
- Android Controller → Log Repository: records events (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/core/ConnectionController.kt`)
- HEV Tunnel Engine → Log Repository: writes logs (evidence: `app/src/main/java/io/github/immaghzbad/aetherst/core/HevTun2SocksEngine.kt`)
- Shared UI → IP Lookup: shows lookup (evidence: `README.md`)
- Shared UI → Diagnostics: offers tests (evidence: `README.md`)