# sammyzi/warden architecture

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

- Interactive diagram: https://gitdiagram.com/sammyzi/warden
- Repository: https://github.com/sammyzi/warden

## Overview

Warden is a no-root Android firewall: Android sends app traffic through its local VPN, where the engine consults rules and either permits or blocks it; events then support on-device history and investigation screens. Users configure app/domain access, blocklists, and DNS, and inspect activity through the dashboard, app details, live log, and globe. The graph preserves these documented capabilities, but some subsystem links rely on README descriptions or indexed references because their implementation excerpts were not shown.

Main entry points: [`app/src/main/java/dev/warden/Shell.kt`](https://github.com/sammyzi/warden/blob/main/app/src/main/java/dev/warden/Shell.kt) (Navigation shell), [`core-rules/src/main/java/dev/warden/rules/Rules.kt`](https://github.com/sammyzi/warden/blob/main/core-rules/src/main/java/dev/warden/rules/Rules.kt) (Rule evaluation), [`feature-apps/src/main/java/dev/warden/apps/AppDetail.kt`](https://github.com/sammyzi/warden/blob/main/feature-apps/src/main/java/dev/warden/apps/AppDetail.kt) (App list and detail), [`core-engine/src/main/java/dev/warden/engine/WardenVpnService.kt`](https://github.com/sammyzi/warden/blob/main/core-engine/src/main/java/dev/warden/engine/WardenVpnService.kt) (Local VPN service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_activity["Activity entry<br/>[MainActivity.kt]"]
  node_shell["Navigation shell<br/>[Shell.kt]"]
end

subgraph group_engine["VPN and rules"]
  node_vpn["Local VPN service"]
  node_tile["Quick Settings tile"]
  node_events["Network events<br/>[NetEvent.kt]"]
  node_rules["Rule evaluation<br/>[Rules.kt]"]
  node_app_rules["Per-app access<br/>[AppRules.kt]"]
  node_blocklists["Blocklists and trackers<br/>[Blocklists.kt]"]
  node_dns["DNS configuration<br/>[Dns.kt]"]
end

subgraph group_data["On-device records"]
  node_history[("History store<br/>[History.kt]")]
  node_usage["System data usage<br/>[SystemUsage.kt]"]
end

subgraph group_features["Firewall features"]
  node_dashboard["Dashboard and data<br/>[DashboardScreen.kt]"]
  node_apps["App list and detail<br/>[AppDetail.kt]"]
  node_reports["Privacy report cards<br/>[ReportCard.kt]"]
  node_live["Live log<br/>[LogScreen.kt]"]
  node_map["Traffic globe<br/>[MapScreen.kt]"]
  node_geo["Country lookup<br/>[Geo.kt]"]
  node_globe["Globe rendering<br/>[Globe.kt]"]
end

subgraph group_config["Configuration"]
  node_settings["Settings and rules<br/>[SettingsScreen.kt]"]
end

node_user(("Phone user"))
node_android(("Android traffic"))
node_internet(("Internet"))
node_sources(("List providers"))

node_user -->|"opens app"| node_activity
node_activity -->|"starts shell"| node_shell
node_shell -->|"shows tab"| node_dashboard
node_shell -->|"shows tab"| node_apps
node_shell -->|"shows tab"| node_live
node_shell -->|"shows tab"| node_map
node_shell -->|"shows tab"| node_settings
node_user -->|"toggles protection"| node_tile
node_tile -->|"starts or stops"| node_vpn
node_android -->|"routes traffic"| node_vpn
node_vpn -->|"asks verdict"| node_rules
node_rules -->|"checks app rule"| node_app_rules
node_rules -->|"checks lists"| node_blocklists
node_rules -->|"checks DNS"| node_dns
node_vpn -->|"allows traffic"| node_internet
node_vpn -->|"records activity"| node_events
node_events -->|"buffers and stores"| node_history
node_dashboard -->|"reads summaries"| node_history
node_dashboard -->|"reads usage"| node_usage
node_apps -->|"shows app activity"| node_events
node_apps -->|"sets app access"| node_app_rules
node_apps -->|"sets domain rules"| node_rules
node_apps -->|"opens report"| node_reports
node_reports -->|"reads history"| node_history
node_live -->|"shows activity"| node_events
node_map -->|"reads connections"| node_history
node_map -->|"filters events"| node_events
node_map -->|"renders globe"| node_globe
node_globe -->|"uses country data"| node_geo
node_settings -->|"edits rules"| node_rules
node_settings -->|"configures lists"| node_blocklists
node_settings -->|"configures DNS"| node_dns
node_blocklists -->|"downloads lists"| node_sources

click node_activity "https://github.com/sammyzi/warden/blob/main/app/src/main/java/dev/warden/MainActivity.kt"
click node_shell "https://github.com/sammyzi/warden/blob/main/app/src/main/java/dev/warden/Shell.kt"
click node_dashboard "https://github.com/sammyzi/warden/blob/main/feature-dashboard/src/main/java/dev/warden/dashboard/DashboardScreen.kt"
click node_apps "https://github.com/sammyzi/warden/blob/main/feature-apps/src/main/java/dev/warden/apps/AppDetail.kt"
click node_reports "https://github.com/sammyzi/warden/blob/main/feature-apps/src/main/java/dev/warden/apps/ReportCard.kt"
click node_live "https://github.com/sammyzi/warden/blob/main/feature-logs/src/main/java/dev/warden/logs/LogScreen.kt"
click node_map "https://github.com/sammyzi/warden/blob/main/feature-map/src/main/java/dev/warden/map/MapScreen.kt"
click node_geo "https://github.com/sammyzi/warden/blob/main/feature-map/src/main/java/dev/warden/map/Geo.kt"
click node_globe "https://github.com/sammyzi/warden/blob/main/feature-map/src/main/java/dev/warden/map/Globe.kt"
click node_settings "https://github.com/sammyzi/warden/blob/main/feature-settings/src/main/java/dev/warden/settings/SettingsScreen.kt"
click node_vpn "https://github.com/sammyzi/warden/blob/main/core-engine/src/main/java/dev/warden/engine/WardenVpnService.kt"
click node_tile "https://github.com/sammyzi/warden/blob/main/core-engine/src/main/java/dev/warden/engine/ProtectionTileService.kt"
click node_events "https://github.com/sammyzi/warden/blob/main/core-engine/src/main/java/dev/warden/engine/NetEvent.kt"
click node_rules "https://github.com/sammyzi/warden/blob/main/core-rules/src/main/java/dev/warden/rules/Rules.kt"
click node_app_rules "https://github.com/sammyzi/warden/blob/main/core-rules/src/main/java/dev/warden/rules/AppRules.kt"
click node_blocklists "https://github.com/sammyzi/warden/blob/main/core-rules/src/main/java/dev/warden/rules/Blocklists.kt"
click node_dns "https://github.com/sammyzi/warden/blob/main/core-rules/src/main/java/dev/warden/rules/Dns.kt"
click node_history "https://github.com/sammyzi/warden/blob/main/core-data/src/main/java/dev/warden/data/History.kt"
click node_usage "https://github.com/sammyzi/warden/blob/main/core-data/src/main/java/dev/warden/data/SystemUsage.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_activity,node_shell,node_user toneBlue
class node_vpn,node_tile,node_events,node_rules,node_app_rules,node_blocklists,node_dns toneAmber
class node_history,node_usage toneMint
class node_dashboard,node_apps,node_reports,node_live,node_map,node_geo,node_globe toneRose
class node_settings,node_android,node_internet,node_sources toneIndigo
```

## Components

### App shell

- [Activity entry](https://github.com/sammyzi/warden/blob/main/app/src/main/java/dev/warden/MainActivity.kt): `app/src/main/java/dev/warden/MainActivity.kt`
- [Navigation shell](https://github.com/sammyzi/warden/blob/main/app/src/main/java/dev/warden/Shell.kt): `app/src/main/java/dev/warden/Shell.kt`

### VPN and rules

- [Local VPN service](https://github.com/sammyzi/warden/blob/main/core-engine/src/main/java/dev/warden/engine/WardenVpnService.kt): `core-engine/src/main/java/dev/warden/engine/WardenVpnService.kt`
- [Quick Settings tile](https://github.com/sammyzi/warden/blob/main/core-engine/src/main/java/dev/warden/engine/ProtectionTileService.kt): `core-engine/src/main/java/dev/warden/engine/ProtectionTileService.kt`
- [Network events](https://github.com/sammyzi/warden/blob/main/core-engine/src/main/java/dev/warden/engine/NetEvent.kt): `core-engine/src/main/java/dev/warden/engine/NetEvent.kt`
- [Rule evaluation](https://github.com/sammyzi/warden/blob/main/core-rules/src/main/java/dev/warden/rules/Rules.kt): `core-rules/src/main/java/dev/warden/rules/Rules.kt`
- [Per-app access](https://github.com/sammyzi/warden/blob/main/core-rules/src/main/java/dev/warden/rules/AppRules.kt): `core-rules/src/main/java/dev/warden/rules/AppRules.kt`
- [Blocklists and trackers](https://github.com/sammyzi/warden/blob/main/core-rules/src/main/java/dev/warden/rules/Blocklists.kt): `core-rules/src/main/java/dev/warden/rules/Blocklists.kt`
- [DNS configuration](https://github.com/sammyzi/warden/blob/main/core-rules/src/main/java/dev/warden/rules/Dns.kt): `core-rules/src/main/java/dev/warden/rules/Dns.kt`

### On-device records

- [History store](https://github.com/sammyzi/warden/blob/main/core-data/src/main/java/dev/warden/data/History.kt): `core-data/src/main/java/dev/warden/data/History.kt`
- [System data usage](https://github.com/sammyzi/warden/blob/main/core-data/src/main/java/dev/warden/data/SystemUsage.kt): `core-data/src/main/java/dev/warden/data/SystemUsage.kt`

### Firewall features

- [Dashboard and data](https://github.com/sammyzi/warden/blob/main/feature-dashboard/src/main/java/dev/warden/dashboard/DashboardScreen.kt): `feature-dashboard/src/main/java/dev/warden/dashboard/DashboardScreen.kt`
- [App list and detail](https://github.com/sammyzi/warden/blob/main/feature-apps/src/main/java/dev/warden/apps/AppDetail.kt): `feature-apps/src/main/java/dev/warden/apps/AppDetail.kt`
- [Privacy report cards](https://github.com/sammyzi/warden/blob/main/feature-apps/src/main/java/dev/warden/apps/ReportCard.kt): `feature-apps/src/main/java/dev/warden/apps/ReportCard.kt`
- [Live log](https://github.com/sammyzi/warden/blob/main/feature-logs/src/main/java/dev/warden/logs/LogScreen.kt): `feature-logs/src/main/java/dev/warden/logs/LogScreen.kt`
- [Traffic globe](https://github.com/sammyzi/warden/blob/main/feature-map/src/main/java/dev/warden/map/MapScreen.kt): `feature-map/src/main/java/dev/warden/map/MapScreen.kt`
- [Country lookup](https://github.com/sammyzi/warden/blob/main/feature-map/src/main/java/dev/warden/map/Geo.kt): `feature-map/src/main/java/dev/warden/map/Geo.kt`
- [Globe rendering](https://github.com/sammyzi/warden/blob/main/feature-map/src/main/java/dev/warden/map/Globe.kt): `feature-map/src/main/java/dev/warden/map/Globe.kt`

### Configuration

- [Settings and rules](https://github.com/sammyzi/warden/blob/main/feature-settings/src/main/java/dev/warden/settings/SettingsScreen.kt): `feature-settings/src/main/java/dev/warden/settings/SettingsScreen.kt`

### Other components

- **Phone user**
- **Android traffic**
- **Internet**
- **List providers**

## Connections

- Phone user → Activity entry: opens app (evidence: `app/src/main/java/dev/warden/MainActivity.kt`)
- Activity entry → Navigation shell: starts shell (evidence: `app/src/main/java/dev/warden/MainActivity.kt`)
- Navigation shell → Dashboard and data: shows tab (evidence: `app/src/main/java/dev/warden/Shell.kt`)
- Navigation shell → App list and detail: shows tab (evidence: `app/src/main/java/dev/warden/Shell.kt`)
- Navigation shell → Live log: shows tab (evidence: `app/src/main/java/dev/warden/Shell.kt`)
- Navigation shell → Traffic globe: shows tab (evidence: `app/src/main/java/dev/warden/Shell.kt`)
- Navigation shell → Settings and rules: shows tab (evidence: `app/src/main/java/dev/warden/Shell.kt`)
- Phone user → Quick Settings tile: toggles protection (evidence: `core-engine/src/main/java/dev/warden/engine/ProtectionTileService.kt`)
- Quick Settings tile → Local VPN service: starts or stops (evidence: `core-engine/src/main/java/dev/warden/engine/ProtectionTileService.kt`)
- Android traffic → Local VPN service: routes traffic (evidence: `README.md`)
- Local VPN service → Rule evaluation: asks verdict (evidence: `README.md`)
- Rule evaluation → Per-app access: checks app rule (evidence: `core-rules/src/main/java/dev/warden/rules/Rules.kt`)
- Rule evaluation → Blocklists and trackers: checks lists (evidence: `core-rules/src/main/java/dev/warden/rules/Rules.kt`)
- Rule evaluation → DNS configuration: checks DNS (evidence: `core-rules/src/main/java/dev/warden/rules/Rules.kt`)
- Local VPN service → Internet: allows traffic (evidence: `README.md`)
- Local VPN service → Network events: records activity (evidence: `README.md`)
- Network events → History store: buffers and stores (evidence: `core-data/src/main/java/dev/warden/data/History.kt`)
- Dashboard and data → History store: reads summaries (evidence: `feature-dashboard/src/main/java/dev/warden/dashboard/DashboardScreen.kt`)
- Dashboard and data → System data usage: reads usage
- App list and detail → Network events: shows app activity (evidence: `feature-apps/src/main/java/dev/warden/apps/AppDetail.kt`)
- App list and detail → Per-app access: sets app access (evidence: `feature-apps/src/main/java/dev/warden/apps/AppDetail.kt`)
- App list and detail → Rule evaluation: sets domain rules (evidence: `feature-apps/src/main/java/dev/warden/apps/AppDetail.kt`)
- App list and detail → Privacy report cards: opens report
- Privacy report cards → History store: reads history (evidence: `feature-apps/src/main/java/dev/warden/apps/ReportCard.kt`)
- Live log → Network events: shows activity (evidence: `feature-logs/src/main/java/dev/warden/logs/LogScreen.kt`)
- Traffic globe → History store: reads connections (evidence: `feature-map/src/main/java/dev/warden/map/MapScreen.kt`)
- Traffic globe → Network events: filters events (evidence: `feature-map/src/main/java/dev/warden/map/MapScreen.kt`)
- Traffic globe → Globe rendering: renders globe (evidence: `feature-map/src/main/java/dev/warden/map/MapScreen.kt`)
- Globe rendering → Country lookup: uses country data (evidence: `feature-map/src/main/java/dev/warden/map/Globe.kt`)
- Settings and rules → Rule evaluation: edits rules (evidence: `feature-settings/src/main/java/dev/warden/settings/SettingsScreen.kt`)
- Settings and rules → Blocklists and trackers: configures lists (evidence: `feature-settings/src/main/java/dev/warden/settings/SettingsScreen.kt`)
- Settings and rules → DNS configuration: configures DNS
- Blocklists and trackers → List providers: downloads lists (evidence: `core-rules/src/main/java/dev/warden/rules/Blocklists.kt`)