# samaliyan/iptray architecture

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

- Interactive diagram: https://gitdiagram.com/samaliyan/iptray
- Repository: https://github.com/samaliyan/iptray

## Overview

IPTray is a Windows tray application for monitoring public IP, geolocation, and VPN/proxy state. Its main workflow is the app's fetch loop: choose a network route, query IP-check endpoints, resolve location, apply user corrections, and update the tray badge and notifications. The README also documents settings, network-triggered refresh, IPv6 leak hints, and diagnostics. Source excerpts establish several core calls; some UI and event wiring is unsampled, so those relationships are omitted or marked unverified.

Main entry points: [`main.go`](https://github.com/samaliyan/iptray/blob/main/main.go) (Tray app and fetch loop), [`diag.go`](https://github.com/samaliyan/iptray/blob/main/diag.go) (Route diagnostics), [`lookup.go`](https://github.com/samaliyan/iptray/blob/main/lookup.go) (Location consensus), [`logic.go`](https://github.com/samaliyan/iptray/blob/main/logic.go) (Route and notification logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Tray application"]
  node_app["Tray app and fetch loop<br/>[main.go]"]
  node_badge["Badge rendering<br/>[icon.go]"]
  node_diag["Route diagnostics<br/>[diag.go]"]
  node_diagnostic_file["Diagnostic report"]
end

subgraph group_network["Network and lookup"]
  node_ipchecks["IP consensus<br/>[lookup.go]"]
  node_geolocation["Location consensus<br/>[lookup.go]"]
  node_geo_cache[("Location cache<br/>[lookup.go]")]
  node_http_fetch["Built-in HTTP fetcher<br/>[lookup.go]"]
end

subgraph group_state["Settings and decisions"]
  node_settings["Settings<br/>[config.go]"]
  node_decisions["Route and notification logic<br/>[logic.go]"]
  node_country_names["Country names<br/>[countries.go]"]
end

subgraph group_windows["Windows integration"]
  node_system_fetch["WinINet fetcher<br/>[wininet_windows.go]"]
  node_pac["PAC evaluation<br/>[pac_windows.go]"]
  node_proxy["Proxy settings<br/>[proxy_windows.go]"]
  node_network_events["Network change watcher<br/>[watch_windows.go]"]
  node_ui["Windows tray UI<br/>[win.go]"]
  node_darkmode["Dark-mode support"]
  node_installer["Per-user installer<br/>[main.go]"]
  node_uninstaller["Uninstaller"]
end

node_user(("User"))
node_ip_services(("IP-check services"))
node_geo_services(("Geolocation services"))

node_app -.->|"reads settings"| node_settings
node_app -.->|"plans routes"| node_decisions
node_app -.->|"checks IP"| node_ipchecks
node_app -->|"locates IP"| node_geolocation
node_app -.->|"updates tray"| node_ui
node_app -->|"renders badge"| node_badge
node_app -.->|"reacts to changes"| node_network_events
node_ipchecks -->|"queries"| node_ip_services
node_geolocation -->|"queries"| node_geo_services
node_geolocation -->|"stores results"| node_geo_cache
node_app -.->|"uses system route"| node_system_fetch
node_app -.->|"uses built-in route"| node_http_fetch
node_decisions -.->|"plans PAC route"| node_pac
node_decisions -.->|"reads proxy plan"| node_proxy
node_diag -->|"tests routes"| node_system_fetch
node_diag -->|"queries endpoints"| node_ip_services
node_diag -->|"locates observed IPs"| node_geolocation
node_diag -->|"reports PAC decisions"| node_pac
node_diag -->|"writes report"| node_diagnostic_file
node_user -.->|"uses tray"| node_app
node_user -.->|"requests diagnosis"| node_diag
node_user -.->|"edits settings"| node_settings
node_badge -.->|"shows country"| node_country_names
node_ui -.->|"applies theme"| node_darkmode
node_installer -->|"installs and starts"| node_app
node_uninstaller -->|"stops instance"| node_app

click node_app "https://github.com/samaliyan/iptray/blob/main/main.go"
click node_badge "https://github.com/samaliyan/iptray/blob/main/icon.go"
click node_diag "https://github.com/samaliyan/iptray/blob/main/diag.go"
click node_settings "https://github.com/samaliyan/iptray/blob/main/config.go"
click node_decisions "https://github.com/samaliyan/iptray/blob/main/logic.go"
click node_ipchecks "https://github.com/samaliyan/iptray/blob/main/lookup.go"
click node_geolocation "https://github.com/samaliyan/iptray/blob/main/lookup.go"
click node_geo_cache "https://github.com/samaliyan/iptray/blob/main/lookup.go"
click node_system_fetch "https://github.com/samaliyan/iptray/blob/main/wininet_windows.go"
click node_http_fetch "https://github.com/samaliyan/iptray/blob/main/lookup.go"
click node_pac "https://github.com/samaliyan/iptray/blob/main/pac_windows.go"
click node_proxy "https://github.com/samaliyan/iptray/blob/main/proxy_windows.go"
click node_network_events "https://github.com/samaliyan/iptray/blob/main/watch_windows.go"
click node_ui "https://github.com/samaliyan/iptray/blob/main/win.go"
click node_darkmode "https://github.com/samaliyan/iptray/blob/main/darkmode_windows.go"
click node_country_names "https://github.com/samaliyan/iptray/blob/main/countries.go"
click node_installer "https://github.com/samaliyan/iptray/blob/main/setup/main.go"
click node_uninstaller "https://github.com/samaliyan/iptray/blob/main/uninstall_windows.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_badge,node_diag,node_diagnostic_file,node_user toneBlue
class node_ipchecks,node_geolocation,node_geo_cache,node_http_fetch toneAmber
class node_settings,node_decisions,node_country_names toneMint
class node_system_fetch,node_pac,node_proxy,node_network_events,node_ui,node_darkmode,node_installer,node_uninstaller toneRose
class node_ip_services,node_geo_services toneIndigo
```

## Components

### Tray application

- [Tray app and fetch loop](https://github.com/samaliyan/iptray/blob/main/main.go): `main.go`
- [Badge rendering](https://github.com/samaliyan/iptray/blob/main/icon.go): `icon.go`
- [Route diagnostics](https://github.com/samaliyan/iptray/blob/main/diag.go): `diag.go`
- **Diagnostic report**

### Network and lookup

- [IP consensus](https://github.com/samaliyan/iptray/blob/main/lookup.go): `lookup.go`
- [Location consensus](https://github.com/samaliyan/iptray/blob/main/lookup.go): `lookup.go`
- [Location cache](https://github.com/samaliyan/iptray/blob/main/lookup.go): `lookup.go`
- [Built-in HTTP fetcher](https://github.com/samaliyan/iptray/blob/main/lookup.go): `lookup.go`

### Settings and decisions

- [Settings](https://github.com/samaliyan/iptray/blob/main/config.go): `config.go`
- [Route and notification logic](https://github.com/samaliyan/iptray/blob/main/logic.go): `logic.go`
- [Country names](https://github.com/samaliyan/iptray/blob/main/countries.go): `countries.go`

### Windows integration

- [WinINet fetcher](https://github.com/samaliyan/iptray/blob/main/wininet_windows.go): `wininet_windows.go`
- [PAC evaluation](https://github.com/samaliyan/iptray/blob/main/pac_windows.go): `pac_windows.go`
- [Proxy settings](https://github.com/samaliyan/iptray/blob/main/proxy_windows.go): `proxy_windows.go`
- [Network change watcher](https://github.com/samaliyan/iptray/blob/main/watch_windows.go): `watch_windows.go`
- [Windows tray UI](https://github.com/samaliyan/iptray/blob/main/win.go): `win.go`
- [Dark-mode support](https://github.com/samaliyan/iptray/blob/main/darkmode_windows.go): `darkmode_windows.go`
- [Per-user installer](https://github.com/samaliyan/iptray/blob/main/setup/main.go): `setup/main.go`
- [Uninstaller](https://github.com/samaliyan/iptray/blob/main/uninstall_windows.go): `uninstall_windows.go`

### Other components

- **User**
- **IP-check services**
- **Geolocation services**

## Connections

- Tray app and fetch loop → Settings: reads settings
- Tray app and fetch loop → Route and notification logic: plans routes
- Tray app and fetch loop → IP consensus: checks IP
- Tray app and fetch loop → Location consensus: locates IP (evidence: `main.go`)
- Tray app and fetch loop → Windows tray UI: updates tray
- Tray app and fetch loop → Badge rendering: renders badge (evidence: `main.go`)
- Tray app and fetch loop → Network change watcher: reacts to changes
- IP consensus → IP-check services: queries (evidence: `lookup.go`)
- Location consensus → Geolocation services: queries (evidence: `lookup.go`)
- Location consensus → Location cache: stores results (evidence: `lookup.go`)
- Tray app and fetch loop → WinINet fetcher: uses system route
- Tray app and fetch loop → Built-in HTTP fetcher: uses built-in route
- Route and notification logic → PAC evaluation: plans PAC route
- Route and notification logic → Proxy settings: reads proxy plan
- Route diagnostics → WinINet fetcher: tests routes (evidence: `diag.go`)
- Route diagnostics → IP-check services: queries endpoints (evidence: `diag.go`)
- Route diagnostics → Location consensus: locates observed IPs (evidence: `diag.go`)
- Route diagnostics → PAC evaluation: reports PAC decisions (evidence: `diag.go`)
- Route diagnostics → Diagnostic report: writes report (evidence: `diag.go`)
- User → Tray app and fetch loop: uses tray
- User → Route diagnostics: requests diagnosis (evidence: `README.md`)
- User → Settings: edits settings (evidence: `README.md`)
- Badge rendering → Country names: shows country
- Windows tray UI → Dark-mode support: applies theme
- Per-user installer → Tray app and fetch loop: installs and starts (evidence: `setup/main.go`)
- Uninstaller → Tray app and fetch loop: stops instance (evidence: `uninstall_windows.go`)
