# tintinworkstation/mesh architecture

> Architecture diagram of the GitHub repository tintinworkstation/mesh, 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/tintinworkstation/mesh
- Repository: https://github.com/tintinworkstation/mesh

## Overview

MESH is a forensic networking suite: analysts use an Android client and desktop tooling to connect to mobile devices over an encrypted overlay, while operators configure networks and access keys through a web control plane. The Android path shown here runs from app/UI state through a local API into the libtailscale engine; the control-plane UI manages networks, policies, and enrollment keys. The README documents relay fallback and optional self-hosted coordination/DERP. Some UI routes and backend implementations are unsampled, so their internal links are omitted or cited only as documented.

Main entry points: [`android-client/android/src/main/java/com/barghest/mesh/App.kt`](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/App.kt) (Android app), [`control-plane/mesh-ui/src/api/useNetworks.ts`](https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/useNetworks.ts) (Network management), [`android-client/android/src/main/java/com/barghest/mesh/ui/localapi/Client.kt`](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/localapi/Client.kt) (Local API client), [`control-plane/mesh-ui/src/api/client.ts`](https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/client.ts) (Control API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android client"]
  node_android_app["Android app<br/>[App.kt]"]
  node_android_screen["App screens<br/>[MainView.kt]"]
  node_app_state["App state<br/>[AppViewModel.kt]"]
  node_local_api["Local API client<br/>[Client.kt]"]
  node_ipn_models["IPN models<br/>[Ipn.kt]"]
  node_notifier["Engine notifications<br/>[Notifier.kt]"]
  node_mesh_engine["Mesh engine<br/>[backend.go]"]
  node_subnet_ui["Subnet routing UI"]
  node_subnet_state["Subnet routing state"]
  node_vpn_os["Android VPN service"]
end

subgraph group_web["Control-plane UI"]
  node_web_ui["Web UI<br/>[main.tsx]"]
  node_network_hooks["Network management<br/>[useNetworks.ts]"]
  node_key_hooks["Enrollment keys<br/>[usePreAuthKeys.ts]"]
  node_policy_hooks["Policy API<br/>[usePolicy.ts]"]
  node_acl_generator["ACL generation"]
  node_api_client["Control API client<br/>[client.ts]"]
end

subgraph group_provision["Provisioning service"]
  node_provision_server["Provisioning server<br/>[main.go]"]
  node_deployment_api["Deployment API<br/>[handler.go]"]
  node_admin_cli["Provisioning admin<br/>[main.go]"]
  node_admin_api["Admin API<br/>[handler.go]"]
  node_provision_state[("Provisioning state<br/>[registry.go]")]
end

subgraph group_analyst["Analyst tooling"]
  node_adb_commands["ADB commands<br/>[adbcollect.go]"]
  node_adb_pairing["ADB pairing<br/>[adbpair.go]"]
end

node_analyst_user(("Forensic analyst"))
node_control_operator(("Operator"))
node_control_api["Control-plane API"]
node_mobile_device(("Mobile device"))
node_overlay_peer(("Overlay peer"))
node_derp_relay["DERP relay"]

node_analyst_user -->|"connects device"| node_android_app
node_android_app -->|"uses"| node_local_api
node_android_app -->|"initializes"| node_app_state
node_android_app -->|"starts"| node_notifier
node_local_api -->|"gets engine"| node_android_app
node_local_api -->|"transfers state"| node_ipn_models
node_notifier -->|"watches notifications"| node_mesh_engine
node_android_app -->|"initializes engine"| node_mesh_engine
node_subnet_ui -->|"renders and updates"| node_subnet_state
node_subnet_state -->|"updates preferences"| node_local_api
node_control_operator -->|"manages network"| node_web_ui
node_web_ui -.->|"uses management"| node_network_hooks
node_web_ui -.->|"manages enrollment"| node_key_hooks
node_network_hooks -->|"sends requests"| node_api_client
node_network_hooks -->|"generates policy"| node_acl_generator
node_network_hooks -->|"parses policy"| node_policy_hooks
node_key_hooks -->|"sends requests"| node_api_client
node_key_hooks -->|"adds network tag"| node_acl_generator
node_policy_hooks -->|"sends requests"| node_api_client
node_api_client -->|"calls API"| node_control_api
node_provision_server -->|"serves"| node_deployment_api
node_provision_server -->|"uses state"| node_provision_state
node_provision_server -.->|"registers admin API"| node_admin_api
node_admin_cli -->|"uses"| node_admin_api
node_admin_api -->|"reads state"| node_provision_state
node_deployment_api -->|"reads state"| node_provision_state
node_analyst_user -->|"runs acquisition"| node_adb_commands
node_adb_commands -.->|"collects over ADB"| node_mobile_device
node_analyst_user -->|"pairs device"| node_adb_pairing
node_android_app -->|"connects encrypted"| node_overlay_peer
node_overlay_peer -.->|"relays if needed"| node_derp_relay
node_android_app -.->|"configures VPN"| node_vpn_os

click node_android_app "https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/App.kt"
click node_android_screen "https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/view/MainView.kt"
click node_app_state "https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/viewModel/AppViewModel.kt"
click node_local_api "https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/localapi/Client.kt"
click node_ipn_models "https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/model/Ipn.kt"
click node_notifier "https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/notifier/Notifier.kt"
click node_mesh_engine "https://github.com/tintinworkstation/mesh/blob/main/android-client/libtailscale/backend.go"
click node_subnet_ui "https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/view/SubnetRoutingView.kt"
click node_subnet_state "https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/viewModel/SubnetRoutingViewModel.kt"
click node_web_ui "https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/main.tsx"
click node_network_hooks "https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/useNetworks.ts"
click node_key_hooks "https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/usePreAuthKeys.ts"
click node_policy_hooks "https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/usePolicy.ts"
click node_acl_generator "https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/lib/aclPolicyGenerator.ts"
click node_api_client "https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/client.ts"
click node_provision_server "https://github.com/tintinworkstation/mesh/blob/main/provisioning/cmd/server/main.go"
click node_deployment_api "https://github.com/tintinworkstation/mesh/blob/main/provisioning/internal/api/handler.go"
click node_admin_cli "https://github.com/tintinworkstation/mesh/blob/main/provisioning/cmd/admin/main.go"
click node_admin_api "https://github.com/tintinworkstation/mesh/blob/main/provisioning/internal/adminapi/handler.go"
click node_provision_state "https://github.com/tintinworkstation/mesh/blob/main/provisioning/internal/state/registry.go"
click node_adb_commands "https://github.com/tintinworkstation/mesh/blob/main/analyst/cmd/adbcollect.go"
click node_adb_pairing "https://github.com/tintinworkstation/mesh/blob/main/analyst/cmd/adbpair.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_android_app,node_android_screen,node_app_state,node_local_api,node_ipn_models,node_notifier,node_mesh_engine,node_subnet_ui,node_subnet_state,node_vpn_os toneBlue
class node_web_ui,node_network_hooks,node_key_hooks,node_policy_hooks,node_acl_generator,node_api_client toneAmber
class node_provision_server,node_deployment_api,node_admin_cli,node_admin_api,node_provision_state,node_control_api toneMint
class node_adb_commands,node_adb_pairing toneRose
class node_analyst_user,node_control_operator,node_mobile_device,node_overlay_peer,node_derp_relay toneIndigo
```

## Components

### Android client

- [Android app](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/App.kt): `android-client/android/src/main/java/com/barghest/mesh/App.kt`
- [App screens](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/view/MainView.kt): `android-client/android/src/main/java/com/barghest/mesh/ui/view/MainView.kt`
- [App state](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/viewModel/AppViewModel.kt): `android-client/android/src/main/java/com/barghest/mesh/ui/viewModel/AppViewModel.kt`
- [Local API client](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/localapi/Client.kt): `android-client/android/src/main/java/com/barghest/mesh/ui/localapi/Client.kt`
- [IPN models](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/model/Ipn.kt): `android-client/android/src/main/java/com/barghest/mesh/ui/model/Ipn.kt`
- [Engine notifications](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/notifier/Notifier.kt): `android-client/android/src/main/java/com/barghest/mesh/ui/notifier/Notifier.kt`
- [Mesh engine](https://github.com/tintinworkstation/mesh/blob/main/android-client/libtailscale/backend.go): `android-client/libtailscale/backend.go`
- [Subnet routing UI](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/view/SubnetRoutingView.kt): `android-client/android/src/main/java/com/barghest/mesh/ui/view/SubnetRoutingView.kt`
- [Subnet routing state](https://github.com/tintinworkstation/mesh/blob/main/android-client/android/src/main/java/com/barghest/mesh/ui/viewModel/SubnetRoutingViewModel.kt): `android-client/android/src/main/java/com/barghest/mesh/ui/viewModel/SubnetRoutingViewModel.kt`
- **Android VPN service**

### Control-plane UI

- [Web UI](https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/main.tsx): `control-plane/mesh-ui/src/main.tsx`
- [Network management](https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/useNetworks.ts): `control-plane/mesh-ui/src/api/useNetworks.ts`
- [Enrollment keys](https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/usePreAuthKeys.ts): `control-plane/mesh-ui/src/api/usePreAuthKeys.ts`
- [Policy API](https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/usePolicy.ts): `control-plane/mesh-ui/src/api/usePolicy.ts`
- [ACL generation](https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/lib/aclPolicyGenerator.ts): `control-plane/mesh-ui/src/lib/aclPolicyGenerator.ts`
- [Control API client](https://github.com/tintinworkstation/mesh/blob/main/control-plane/mesh-ui/src/api/client.ts): `control-plane/mesh-ui/src/api/client.ts`

### Provisioning service

- [Provisioning server](https://github.com/tintinworkstation/mesh/blob/main/provisioning/cmd/server/main.go): `provisioning/cmd/server/main.go`
- [Deployment API](https://github.com/tintinworkstation/mesh/blob/main/provisioning/internal/api/handler.go): `provisioning/internal/api/handler.go`
- [Provisioning admin](https://github.com/tintinworkstation/mesh/blob/main/provisioning/cmd/admin/main.go): `provisioning/cmd/admin/main.go`
- [Admin API](https://github.com/tintinworkstation/mesh/blob/main/provisioning/internal/adminapi/handler.go): `provisioning/internal/adminapi/handler.go`
- [Provisioning state](https://github.com/tintinworkstation/mesh/blob/main/provisioning/internal/state/registry.go): `provisioning/internal/state/registry.go`

### Analyst tooling

- [ADB commands](https://github.com/tintinworkstation/mesh/blob/main/analyst/cmd/adbcollect.go): `analyst/cmd/adbcollect.go`
- [ADB pairing](https://github.com/tintinworkstation/mesh/blob/main/analyst/cmd/adbpair.go): `analyst/cmd/adbpair.go`

### Other components

- **Forensic analyst**
- **Operator**
- **Control-plane API**
- **Mobile device**
- **Overlay peer**
- **DERP relay**

## Connections

- Forensic analyst → Android app: connects device
- Android app → Local API client: uses (evidence: `android-client/android/src/main/java/com/barghest/mesh/App.kt`)
- Android app → App state: initializes (evidence: `android-client/android/src/main/java/com/barghest/mesh/App.kt`)
- Android app → Engine notifications: starts (evidence: `android-client/android/src/main/java/com/barghest/mesh/App.kt`)
- Local API client → Android app: gets engine (evidence: `android-client/android/src/main/java/com/barghest/mesh/ui/localapi/Client.kt`)
- Local API client → IPN models: transfers state (evidence: `android-client/android/src/main/java/com/barghest/mesh/ui/localapi/Client.kt`)
- Engine notifications → Mesh engine: watches notifications (evidence: `android-client/android/src/main/java/com/barghest/mesh/ui/notifier/Notifier.kt`)
- Android app → Mesh engine: initializes engine (evidence: `android-client/android/src/main/java/com/barghest/mesh/App.kt`)
- Subnet routing UI → Subnet routing state: renders and updates (evidence: `android-client/android/src/main/java/com/barghest/mesh/ui/view/SubnetRoutingView.kt`)
- Subnet routing state → Local API client: updates preferences (evidence: `android-client/android/src/main/java/com/barghest/mesh/ui/viewModel/SubnetRoutingViewModel.kt`)
- Operator → Web UI: manages network
- Web UI → Network management: uses management
- Web UI → Enrollment keys: manages enrollment
- Network management → Control API client: sends requests (evidence: `control-plane/mesh-ui/src/api/useNetworks.ts`)
- Network management → ACL generation: generates policy (evidence: `control-plane/mesh-ui/src/api/useNetworks.ts`)
- Network management → Policy API: parses policy (evidence: `control-plane/mesh-ui/src/api/useNetworks.ts`)
- Enrollment keys → Control API client: sends requests (evidence: `control-plane/mesh-ui/src/api/usePreAuthKeys.ts`)
- Enrollment keys → ACL generation: adds network tag (evidence: `control-plane/mesh-ui/src/api/usePreAuthKeys.ts`)
- Policy API → Control API client: sends requests (evidence: `control-plane/mesh-ui/src/api/usePolicy.ts`)
- Control API client → Control-plane API: calls API
- Provisioning server → Deployment API: serves (evidence: `provisioning/cmd/server/main.go`)
- Provisioning server → Provisioning state: uses state (evidence: `provisioning/cmd/server/main.go`)
- Provisioning server → Admin API: registers admin API
- Provisioning admin → Admin API: uses (evidence: `provisioning/cmd/admin/main.go`)
- Admin API → Provisioning state: reads state (evidence: `provisioning/internal/adminapi/handler.go`)
- Deployment API → Provisioning state: reads state (evidence: `provisioning/internal/api/handler.go`)
- Forensic analyst → ADB commands: runs acquisition
- ADB commands → Mobile device: collects over ADB
- Forensic analyst → ADB pairing: pairs device
- Android app → Overlay peer: connects encrypted
- Overlay peer → DERP relay: relays if needed
- Android app → Android VPN service: configures VPN
