# hypostasis-cat/hypomux architecture

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

- Interactive diagram: https://gitdiagram.com/hypostasis-cat/hypomux
- Repository: https://github.com/hypostasis-cat/hypomux

## Overview

HypoMux is a Windows desktop tool for distributing independent network connections across multiple adapters, with system-proxy and virtual-interface modes. Users select adapters, check link health, configure routing and scheduling, then start aggregation and monitor throughput; the desktop service layer coordinates the separate engine and privileged network operations. The README also documents AI assistance, hotspot and network diagnostics, Steam CDN optimization, rule subscriptions, updates, and appearance customization. Several internal links below follow explicit README descriptions or SOURCE INDEX references; unsampled feature implementations are represented at their supported directory paths.

Main entry points: [`desktop/frontend/src/App.tsx`](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/App.tsx) (React application), [`desktop/frontend/src/platform/services.ts`](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/platform/services.ts) (Service bridge), [`engine/internal/server/server.go`](https://github.com/hypostasis-cat/hypomux/blob/main/engine/internal/server/server.go) (Engine API), [`desktop/frontend/src/components/home/EngineHero.tsx`](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/components/home/EngineHero.tsx) (Aggregation controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop_ui["Desktop experience"]
  node_app["React application<br/>[App.tsx]"]
  node_home["Aggregation controls<br/>[EngineHero.tsx]"]
  node_state["Engine state<br/>[useEngineState.ts]"]
  node_routing["Routing rules<br/>[RoutingPage.tsx]"]
  node_connections["Connections view"]
  node_health["Network health<br/>[HealthPage.tsx]"]
  node_settings_ui["Settings<br/>[SettingsPage.tsx]"]
  node_appearance["Appearance"]
end

subgraph group_desktop_services["Desktop services"]
  node_service_bridge["Service bridge<br/>[services.ts]"]
  node_desktop_host["Desktop host<br/>[main.go]"]
  node_engine_service["Engine service<br/>[engine.go]"]
  node_engine_client["Engine client<br/>[client.go]"]
end

subgraph group_engine["Network engine"]
  node_engine_entry["Engine process<br/>[main.go]"]
  node_server["Engine API<br/>[server.go]"]
  node_proxy["Proxy and scheduler<br/>[server.go]"]
end

subgraph group_network_ops["Network operations"]
  node_tun["TUN lifecycle<br/>[supervisor.go]"]
  node_network_services["Network services"]
end

subgraph group_auxiliary["Product capabilities"]
  node_ai["AI assistant<br/>[ai_service.go]"]
  node_hotspot["Aggregated hotspot<br/>[hotspot.go]"]
  node_steam["Steam CDN<br/>[steam_cdn.go]"]
  node_rules["Rule subscriptions"]
  node_updates["Update service<br/>[updater.go]"]
end

node_user(("User"))
node_external_network(("Network destinations"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_home
node_app -->|"routes to"| node_routing
node_app -->|"routes to"| node_connections
node_app -->|"routes to"| node_health
node_app -->|"routes to"| node_settings_ui
node_app -->|"provides theme"| node_appearance
node_home -->|"controls"| node_state
node_state -->|"calls"| node_service_bridge
node_routing -->|"calls"| node_service_bridge
node_settings_ui -->|"calls"| node_service_bridge
node_health -->|"calls"| node_service_bridge
node_service_bridge -->|"invokes bindings"| node_desktop_host
node_desktop_host -->|"provides services"| node_engine_service
node_engine_service -->|"sends requests"| node_engine_client
node_engine_client -.->|"communicates"| node_engine_entry
node_engine_entry -->|"starts API"| node_server
node_server -->|"creates proxy"| node_proxy
node_server -->|"activates"| node_tun
node_proxy -->|"forwards traffic"| node_external_network
node_server -.->|"uses network controls"| node_network_services
node_user -.->|"requests assistance"| node_ai
node_user -.->|"configures hotspot"| node_hotspot
node_user -.->|"uses optimization"| node_steam
node_user -.->|"manages subscriptions"| node_rules
node_user -.->|"checks updates"| node_updates
node_ai -.->|"contacts model API"| node_external_network

click node_app "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/App.tsx"
click node_home "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/components/home/EngineHero.tsx"
click node_state "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/state/useEngineState.ts"
click node_routing "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/pages/RoutingPage.tsx"
click node_connections "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/pages/ConnectionsPage.tsx"
click node_health "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/pages/HealthPage.tsx"
click node_settings_ui "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/pages/SettingsPage.tsx"
click node_appearance "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/theme/appearance.store.tsx"
click node_service_bridge "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/platform/services.ts"
click node_desktop_host "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/main.go"
click node_engine_service "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/engine.go"
click node_engine_client "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/engineclient/client.go"
click node_engine_entry "https://github.com/hypostasis-cat/hypomux/blob/main/engine/cmd/hypomux-engine/main.go"
click node_server "https://github.com/hypostasis-cat/hypomux/blob/main/engine/internal/server/server.go"
click node_proxy "https://github.com/hypostasis-cat/hypomux/blob/main/engine/internal/proxy/server.go"
click node_tun "https://github.com/hypostasis-cat/hypomux/blob/main/engine/internal/tun/supervisor.go"
click node_network_services "https://github.com/hypostasis-cat/hypomux/tree/main/desktop/internal/services"
click node_ai "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/ai_service.go"
click node_hotspot "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/hotspot.go"
click node_steam "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/steam_cdn.go"
click node_rules "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/rule_sets_service.go"
click node_updates "https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/updater.go"

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_home,node_state,node_routing,node_connections,node_health,node_settings_ui,node_appearance,node_user toneBlue
class node_service_bridge,node_desktop_host,node_engine_service,node_engine_client toneAmber
class node_engine_entry,node_server,node_proxy toneMint
class node_tun,node_network_services toneRose
class node_ai,node_hotspot,node_steam,node_rules,node_updates,node_external_network toneIndigo
```

## Components

### Desktop experience

- [React application](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/App.tsx): `desktop/frontend/src/App.tsx`
- [Aggregation controls](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/components/home/EngineHero.tsx): `desktop/frontend/src/components/home/EngineHero.tsx`
- [Engine state](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/state/useEngineState.ts): `desktop/frontend/src/state/useEngineState.ts`
- [Routing rules](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/pages/RoutingPage.tsx): `desktop/frontend/src/pages/RoutingPage.tsx`
- [Connections view](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/pages/ConnectionsPage.tsx): `desktop/frontend/src/pages/ConnectionsPage.tsx`
- [Network health](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/pages/HealthPage.tsx): `desktop/frontend/src/pages/HealthPage.tsx`
- [Settings](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/pages/SettingsPage.tsx): `desktop/frontend/src/pages/SettingsPage.tsx`
- [Appearance](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/theme/appearance.store.tsx): `desktop/frontend/src/theme/appearance.store.tsx`

### Desktop services

- [Service bridge](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/frontend/src/platform/services.ts): `desktop/frontend/src/platform/services.ts`
- [Desktop host](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/main.go): `desktop/main.go`
- [Engine service](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/engine.go): `desktop/internal/services/engine.go`
- [Engine client](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/engineclient/client.go): `desktop/internal/engineclient/client.go`

### Network engine

- [Engine process](https://github.com/hypostasis-cat/hypomux/blob/main/engine/cmd/hypomux-engine/main.go): `engine/cmd/hypomux-engine/main.go`
- [Engine API](https://github.com/hypostasis-cat/hypomux/blob/main/engine/internal/server/server.go): `engine/internal/server/server.go`
- [Proxy and scheduler](https://github.com/hypostasis-cat/hypomux/blob/main/engine/internal/proxy/server.go): `engine/internal/proxy/server.go`

### Network operations

- [TUN lifecycle](https://github.com/hypostasis-cat/hypomux/blob/main/engine/internal/tun/supervisor.go): `engine/internal/tun/supervisor.go`
- [Network services](https://github.com/hypostasis-cat/hypomux/tree/main/desktop/internal/services): `desktop/internal/services`

### Product capabilities

- [AI assistant](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/ai_service.go): `desktop/internal/services/ai_service.go`
- [Aggregated hotspot](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/hotspot.go): `desktop/internal/services/hotspot.go`
- [Steam CDN](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/steam_cdn.go): `desktop/internal/services/steam_cdn.go`
- [Rule subscriptions](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/rule_sets_service.go): `desktop/internal/services/rule_sets_service.go`
- [Update service](https://github.com/hypostasis-cat/hypomux/blob/main/desktop/internal/services/updater.go): `desktop/internal/services/updater.go`

### Other components

- **User**
- **Network destinations**

## Connections

- User → React application: uses (evidence: `README.md`)
- React application → Aggregation controls: renders (evidence: `desktop/frontend/src/App.tsx`)
- React application → Routing rules: routes to (evidence: `desktop/frontend/src/App.tsx`)
- React application → Connections view: routes to (evidence: `desktop/frontend/src/App.tsx`)
- React application → Network health: routes to (evidence: `desktop/frontend/src/App.tsx`)
- React application → Settings: routes to (evidence: `desktop/frontend/src/App.tsx`)
- React application → Appearance: provides theme (evidence: `desktop/frontend/src/App.tsx`)
- Aggregation controls → Engine state: controls (evidence: `desktop/frontend/src/components/home/EngineHero.tsx`)
- Engine state → Service bridge: calls (evidence: `desktop/frontend/src/state/useEngineState.ts`)
- Routing rules → Service bridge: calls (evidence: `desktop/frontend/src/pages/RoutingPage.tsx`)
- Settings → Service bridge: calls (evidence: `desktop/frontend/src/platform/services.ts`)
- Network health → Service bridge: calls (evidence: `desktop/frontend/src/platform/services.ts`)
- Service bridge → Desktop host: invokes bindings (evidence: `desktop/frontend/src/platform/services.ts`)
- Desktop host → Engine service: provides services (evidence: `desktop/main.go`)
- Engine service → Engine client: sends requests (evidence: `desktop/internal/services/engine.go`)
- Engine client → Engine process: communicates
- Engine process → Engine API: starts API (evidence: `engine/cmd/hypomux-engine/main.go`)
- Engine API → Proxy and scheduler: creates proxy (evidence: `engine/internal/server/server.go`)
- Engine API → TUN lifecycle: activates (evidence: `engine/internal/server/server.go`)
- Proxy and scheduler → Network destinations: forwards traffic (evidence: `README.md`)
- Engine API → Network services: uses network controls
- User → AI assistant: requests assistance (evidence: `README.md`)
- User → Aggregated hotspot: configures hotspot (evidence: `README.md`)
- User → Steam CDN: uses optimization (evidence: `README.md`)
- User → Rule subscriptions: manages subscriptions (evidence: `README.md`)
- User → Update service: checks updates (evidence: `README.md`)
- AI assistant → Network destinations: contacts model API (evidence: `README.md`)