# horatioconkerhead/gatecrash architecture

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

- Interactive diagram: https://gitdiagram.com/horatioconkerhead/gatecrash
- Repository: https://github.com/horatioconkerhead/gatecrash

## Overview

Gatecrash is a Linux appliance for selectively routing chosen LAN devices through WireGuard using bidirectional ARP spoofing. The user configures a tunnel, discovers and saves devices, enables targets, and starts interception from the web UI; the app tracks device IP changes and applies target-rule updates. The graph also preserves monitoring, TLS, and configuration capabilities. Shell runtime details are limited to README documentation and references in sampled source; unsampled app routes are represented at the app boundary.

Main entry points: [`webui/app.py`](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/app.py) (Web UI and API), [`webui/targets.py`](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/targets.py) (Target rule manager), [`webui/config.py`](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/config.py) (Appliance config), [`webui/devices.py`](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/devices.py) (Saved device resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web control plane"]
  node_app["Web UI and API<br/>[app.py]"]
  node_frontend["UI template<br/>[index.html]"]
  node_settings[("Settings store<br/>[settings.py]")]
  node_tls["TLS certificates<br/>[tls.py]"]
  node_validators["Input validation<br/>[validators.py]"]
end

subgraph group_devices["Device management"]
  node_devicesvc["Saved device resolver<br/>[devices.py]"]
  node_parsing["Network output parsers<br/>[parsing.py]"]
end

subgraph group_routing["Traffic routing"]
  node_config[("Appliance config<br/>[config.py]")]
  node_targets["Target rule manager<br/>[targets.py]"]
  node_runtime["Routing lifecycle<br/>[start.sh]"]
end

subgraph group_support["Appliance services"]
  node_netutils["Network command helpers<br/>[netutils.py]"]
  node_stats["System statistics<br/>[stats.py]"]
end

node_user(("LAN administrator"))
node_browser(("Web browser"))
node_vpn(("WireGuard provider"))
node_lan(("LAN devices"))
node_linux["Linux networking"]
node_service["System service manager"]

node_user -->|"configures through"| node_browser
node_browser -->|"uses"| node_app
node_app -->|"serves UI"| node_frontend
node_app -->|"validates with"| node_validators
node_app -->|"uses"| node_settings
node_app -->|"uses"| node_tls
node_app -->|"reads and writes"| node_config
node_app -->|"manages devices"| node_devicesvc
node_app -->|"applies target changes"| node_targets
node_app -->|"collects status"| node_stats
node_devicesvc -->|"runs network commands"| node_netutils
node_devicesvc -->|"parses neighbor data"| node_parsing
node_devicesvc -->|"updates target config"| node_config
node_config -->|"queries network"| node_netutils
node_config -->|"validates config"| node_validators
node_targets -->|"reads settings"| node_config
node_targets -->|"detects gateway"| node_netutils
node_targets -->|"validates targets"| node_validators
node_targets -->|"installs rules and spoofing"| node_linux
node_runtime -->|"configures forwarding"| node_linux
node_runtime -->|"routes targets through"| node_vpn
node_lan -->|"traffic intercepted"| node_runtime
node_app -->|"starts and stops service"| node_service
node_app -->|"samples system metrics"| node_linux

click node_app "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/app.py"
click node_frontend "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/templates/index.html"
click node_settings "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/settings.py"
click node_tls "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/tls.py"
click node_validators "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/validators.py"
click node_config "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/config.py"
click node_targets "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/targets.py"
click node_runtime "https://github.com/horatioconkerhead/gatecrash/blob/master/start.sh"
click node_devicesvc "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/devices.py"
click node_parsing "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/parsing.py"
click node_netutils "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/netutils.py"
click node_stats "https://github.com/horatioconkerhead/gatecrash/blob/master/webui/stats.py"

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_frontend,node_settings,node_tls,node_validators,node_browser toneBlue
class node_devicesvc,node_parsing toneAmber
class node_config,node_targets,node_runtime toneMint
class node_netutils,node_stats toneRose
class node_user,node_vpn,node_lan,node_linux,node_service toneIndigo
```

## Components

### Web control plane

- [Web UI and API](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/app.py): `webui/app.py`
- [UI template](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/templates/index.html): `webui/templates/index.html`
- [Settings store](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/settings.py): `webui/settings.py`
- [TLS certificates](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/tls.py): `webui/tls.py`
- [Input validation](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/validators.py): `webui/validators.py`

### Device management

- [Saved device resolver](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/devices.py): `webui/devices.py`
- [Network output parsers](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/parsing.py): `webui/parsing.py`

### Traffic routing

- [Appliance config](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/config.py): `webui/config.py`
- [Target rule manager](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/targets.py): `webui/targets.py`
- [Routing lifecycle](https://github.com/horatioconkerhead/gatecrash/blob/master/start.sh): `start.sh`

### Appliance services

- [Network command helpers](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/netutils.py): `webui/netutils.py`
- [System statistics](https://github.com/horatioconkerhead/gatecrash/blob/master/webui/stats.py): `webui/stats.py`

### Other components

- **LAN administrator**
- **Web browser**
- **WireGuard provider**
- **LAN devices**
- **Linux networking**
- **System service manager**

## Connections

- LAN administrator → Web browser: configures through (evidence: `readme.md`)
- Web browser → Web UI and API: uses (evidence: `readme.md`)
- Web UI and API → UI template: serves UI (evidence: `readme.md`)
- Web UI and API → Input validation: validates with (evidence: `webui/app.py`)
- Web UI and API → Settings store: uses (evidence: `webui/app.py`)
- Web UI and API → TLS certificates: uses (evidence: `webui/app.py`)
- Web UI and API → Appliance config: reads and writes (evidence: `webui/app.py`)
- Web UI and API → Saved device resolver: manages devices (evidence: `webui/app.py`)
- Web UI and API → Target rule manager: applies target changes (evidence: `webui/targets.py`)
- Web UI and API → System statistics: collects status (evidence: `webui/app.py`)
- Saved device resolver → Network command helpers: runs network commands (evidence: `webui/devices.py`)
- Saved device resolver → Network output parsers: parses neighbor data (evidence: `webui/devices.py`)
- Saved device resolver → Appliance config: updates target config (evidence: `webui/devices.py`)
- Appliance config → Network command helpers: queries network (evidence: `webui/config.py`)
- Appliance config → Input validation: validates config (evidence: `webui/config.py`)
- Target rule manager → Appliance config: reads settings (evidence: `webui/targets.py`)
- Target rule manager → Network command helpers: detects gateway (evidence: `webui/targets.py`)
- Target rule manager → Input validation: validates targets (evidence: `webui/targets.py`)
- Target rule manager → Linux networking: installs rules and spoofing (evidence: `webui/targets.py`)
- Routing lifecycle → Linux networking: configures forwarding (evidence: `readme.md`)
- Routing lifecycle → WireGuard provider: routes targets through (evidence: `readme.md`)
- LAN devices → Routing lifecycle: traffic intercepted (evidence: `readme.md`)
- Web UI and API → System service manager: starts and stops service (evidence: `webui/app.py`)
- Web UI and API → Linux networking: samples system metrics
