# g3ntrix/shade architecture

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

- Interactive diagram: https://gitdiagram.com/g3ntrix/shade
- Repository: https://github.com/g3ntrix/shade

## Overview

Shade is a guided macOS client for a local traffic-tunneling proxy. Users configure a profile in the setup wizard, start the core from the dashboard or menu bar, and optionally enable macOS system-proxy routing or full-tunnel mode. The Python proxy handles HTTP/SOCKS traffic, optional HTTPS interception and ad blocking, then relays requests through Apps Script; the app also exposes profile sharing, diagnostics, speed checks, and optional exit relays. Some feature links are based on README documentation because their implementations were not sampled.

Main entry points: [`macos-app/Sources/Shade/Models/AppState.swift`](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Models/AppState.swift) (App state), [`src/proxy_server.py`](https://github.com/g3ntrix/shade/blob/main/src/proxy_server.py) (Local proxy), [`macos-app/Sources/Shade/Views/DashboardView.swift`](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Views/DashboardView.swift) (Dashboard), [`src/domain_fronter.py`](https://github.com/g3ntrix/shade/blob/main/src/domain_fronter.py) (Domain-front relay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["macOS client"]
  node_app_ui["App navigation<br/>[ContentView.swift]"]
  node_setup["Guided setup<br/>[SetupView.swift]"]
  node_dashboard["Dashboard"]
  node_menu["Menu controls<br/>[MenuBarView.swift]"]
  node_speed_check["Speed check<br/>[AppState.swift]"]
end

subgraph group_management["State and services"]
  node_settings["App settings<br/>[AppSettings.swift]"]
  node_state["App state<br/>[AppState.swift]"]
  node_config["Config storage<br/>[ConfigStore.swift]"]
  node_core_mgr["Core supervisor<br/>[CoreManager.swift]"]
  node_system_proxy["System proxy<br/>[SystemProxy.swift]"]
  node_cert["Certificate trust<br/>[CertManager.swift]"]
  node_network["Network info<br/>[NetworkInfo.swift]"]
end

subgraph group_proxy["Proxy runtime"]
  node_core_entry["Core entry point<br/>[main.py]"]
  node_proxy_server["Local proxy<br/>[proxy_server.py]"]
  node_mitm["HTTPS interception<br/>[mitm.py]"]
  node_adblock["Ad blocking<br/>[adblock.py]"]
  node_socks["SOCKS relay<br/>[udp_socks_relay.py]"]
end

subgraph group_relay["Relay and integrations"]
  node_domain_relay["Domain-front relay<br/>[domain_fronter.py]"]
  node_h2["HTTP/2 transport<br/>[h2_transport.py]"]
  node_codec["Relay codec<br/>[codec.py]"]
  node_exit_relay["Exit relay option"]
end

node_user(("Mac user"))
node_google{{"Apps Script"}}
node_external_device(("Phone or tablet"))

node_user -->|"uses"| node_app_ui
node_app_ui -->|"routes to"| node_setup
node_app_ui -->|"routes to"| node_dashboard
node_setup -->|"configures"| node_state
node_dashboard -->|"controls"| node_state
node_menu -->|"controls"| node_state
node_state -->|"reads"| node_settings
node_state -->|"writes config"| node_config
node_state -->|"starts core"| node_core_mgr
node_state -->|"installs trust"| node_cert
node_state -->|"enables proxy"| node_system_proxy
node_state -->|"queries"| node_network
node_core_mgr -->|"launches"| node_core_entry
node_core_entry -->|"starts"| node_proxy_server
node_proxy_server -->|"relays requests"| node_domain_relay
node_proxy_server -->|"uses"| node_mitm
node_proxy_server -->|"filters domains"| node_adblock
node_proxy_server -->|"dispatches SOCKS"| node_socks
node_domain_relay -->|"sends requests"| node_h2
node_domain_relay -->|"encodes payloads"| node_codec
node_h2 -->|"uses"| node_codec
node_domain_relay -->|"tunnels through"| node_google
node_external_device -->|"connects by SOCKS"| node_proxy_server
node_dashboard -.->|"offers relay setup"| node_exit_relay
node_dashboard -->|"runs test"| node_speed_check

click node_app_ui "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/ContentView.swift"
click node_setup "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Views/SetupView.swift"
click node_dashboard "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Views/DashboardView.swift"
click node_menu "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Views/MenuBarView.swift"
click node_settings "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Models/AppSettings.swift"
click node_state "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Models/AppState.swift"
click node_config "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/ConfigStore.swift"
click node_core_mgr "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/CoreManager.swift"
click node_system_proxy "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/SystemProxy.swift"
click node_cert "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/CertManager.swift"
click node_network "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/NetworkInfo.swift"
click node_core_entry "https://github.com/g3ntrix/shade/blob/main/main.py"
click node_proxy_server "https://github.com/g3ntrix/shade/blob/main/src/proxy_server.py"
click node_mitm "https://github.com/g3ntrix/shade/blob/main/src/mitm.py"
click node_adblock "https://github.com/g3ntrix/shade/blob/main/src/adblock.py"
click node_socks "https://github.com/g3ntrix/shade/blob/main/src/udp_socks_relay.py"
click node_domain_relay "https://github.com/g3ntrix/shade/blob/main/src/domain_fronter.py"
click node_h2 "https://github.com/g3ntrix/shade/blob/main/src/h2_transport.py"
click node_codec "https://github.com/g3ntrix/shade/blob/main/src/codec.py"
click node_exit_relay "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/ExitRelayPackager.swift"
click node_speed_check "https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Models/AppState.swift"

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_ui,node_setup,node_dashboard,node_menu,node_speed_check,node_user toneBlue
class node_settings,node_state,node_config,node_core_mgr,node_system_proxy,node_cert,node_network toneAmber
class node_core_entry,node_proxy_server,node_mitm,node_adblock,node_socks toneMint
class node_domain_relay,node_h2,node_codec,node_exit_relay toneRose
class node_google,node_external_device toneIndigo
```

## Components

### macOS client

- [App navigation](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/ContentView.swift): `macos-app/Sources/Shade/ContentView.swift`
- [Guided setup](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Views/SetupView.swift): `macos-app/Sources/Shade/Views/SetupView.swift`
- [Dashboard](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Views/DashboardView.swift): `macos-app/Sources/Shade/Views/DashboardView.swift`
- [Menu controls](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Views/MenuBarView.swift): `macos-app/Sources/Shade/Views/MenuBarView.swift`
- [Speed check](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Models/AppState.swift): `macos-app/Sources/Shade/Models/AppState.swift`

### State and services

- [App settings](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Models/AppSettings.swift): `macos-app/Sources/Shade/Models/AppSettings.swift`
- [App state](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Models/AppState.swift): `macos-app/Sources/Shade/Models/AppState.swift`
- [Config storage](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/ConfigStore.swift): `macos-app/Sources/Shade/Services/ConfigStore.swift`
- [Core supervisor](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/CoreManager.swift): `macos-app/Sources/Shade/Services/CoreManager.swift`
- [System proxy](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/SystemProxy.swift): `macos-app/Sources/Shade/Services/SystemProxy.swift`
- [Certificate trust](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/CertManager.swift): `macos-app/Sources/Shade/Services/CertManager.swift`
- [Network info](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/NetworkInfo.swift): `macos-app/Sources/Shade/Services/NetworkInfo.swift`

### Proxy runtime

- [Core entry point](https://github.com/g3ntrix/shade/blob/main/main.py): `main.py`
- [Local proxy](https://github.com/g3ntrix/shade/blob/main/src/proxy_server.py): `src/proxy_server.py`
- [HTTPS interception](https://github.com/g3ntrix/shade/blob/main/src/mitm.py): `src/mitm.py`
- [Ad blocking](https://github.com/g3ntrix/shade/blob/main/src/adblock.py): `src/adblock.py`
- [SOCKS relay](https://github.com/g3ntrix/shade/blob/main/src/udp_socks_relay.py): `src/udp_socks_relay.py`

### Relay and integrations

- [Domain-front relay](https://github.com/g3ntrix/shade/blob/main/src/domain_fronter.py): `src/domain_fronter.py`
- [HTTP/2 transport](https://github.com/g3ntrix/shade/blob/main/src/h2_transport.py): `src/h2_transport.py`
- [Relay codec](https://github.com/g3ntrix/shade/blob/main/src/codec.py): `src/codec.py`
- [Exit relay option](https://github.com/g3ntrix/shade/blob/main/macos-app/Sources/Shade/Services/ExitRelayPackager.swift): `macos-app/Sources/Shade/Services/ExitRelayPackager.swift`

### Other components

- **Mac user**
- **Apps Script**
- **Phone or tablet**

## Connections

- Mac user → App navigation: uses (evidence: `README.md`)
- App navigation → Guided setup: routes to (evidence: `macos-app/Sources/Shade/ContentView.swift`)
- App navigation → Dashboard: routes to (evidence: `macos-app/Sources/Shade/ContentView.swift`)
- Guided setup → App state: configures (evidence: `macos-app/Sources/Shade/Views/SetupView.swift`)
- Dashboard → App state: controls (evidence: `macos-app/Sources/Shade/Views/DashboardView.swift`)
- Menu controls → App state: controls (evidence: `macos-app/Sources/Shade/Views/MenuBarView.swift`)
- App state → App settings: reads (evidence: `macos-app/Sources/Shade/Models/AppState.swift`)
- App state → Config storage: writes config (evidence: `macos-app/Sources/Shade/Models/AppState.swift`)
- App state → Core supervisor: starts core (evidence: `macos-app/Sources/Shade/Models/AppState.swift`)
- App state → Certificate trust: installs trust (evidence: `macos-app/Sources/Shade/Models/AppState.swift`)
- App state → System proxy: enables proxy (evidence: `macos-app/Sources/Shade/Models/AppState.swift`)
- App state → Network info: queries (evidence: `macos-app/Sources/Shade/Views/DashboardView.swift`)
- Core supervisor → Core entry point: launches (evidence: `macos-app/Sources/Shade/Services/CoreManager.swift`)
- Core entry point → Local proxy: starts (evidence: `main.py`)
- Local proxy → Domain-front relay: relays requests (evidence: `src/proxy_server.py`)
- Local proxy → HTTPS interception: uses (evidence: `src/proxy_server.py`)
- Local proxy → Ad blocking: filters domains (evidence: `src/proxy_server.py`)
- Local proxy → SOCKS relay: dispatches SOCKS (evidence: `src/proxy_server.py`)
- Domain-front relay → HTTP/2 transport: sends requests (evidence: `src/domain_fronter.py`)
- Domain-front relay → Relay codec: encodes payloads (evidence: `src/domain_fronter.py`)
- HTTP/2 transport → Relay codec: uses (evidence: `src/h2_transport.py`)
- Domain-front relay → Apps Script: tunnels through (evidence: `README.md`)
- Phone or tablet → Local proxy: connects by SOCKS (evidence: `README.md`)
- Dashboard → Exit relay option: offers relay setup (evidence: `macos-app/Sources/Shade/Views/DashboardView.swift`)
- Dashboard → Speed check: runs test (evidence: `macos-app/Sources/Shade/Views/DashboardView.swift`)
