# blueturboguy07/ghost-location architecture

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

- Interactive diagram: https://gitdiagram.com/blueturboguy07/ghost-location
- Repository: https://github.com/blueturboguy07/ghost-location

## Overview

Ghost is an Electron desktop app for choosing a location or road route and explicitly applying it to an iPhone or Android phone over USB or Wi-Fi. The main flow runs from the renderer’s map, search, and route controls through the desktop controller to a platform adapter, which issues device commands; the controller also manages sessions and recovery. The README documents setup, saved places, reconnection, restore, and telemetry. Some renderer-to-desktop wiring and unsampled subsystem details are not shown, so those links are omitted or marked unverified.

Main entry points: [`backend/controller.mjs`](https://github.com/blueturboguy07/ghost-location/blob/main/backend/controller.mjs) (Session controller), [`electron/main.mjs`](https://github.com/blueturboguy07/ghost-location/blob/main/electron/main.mjs) (Electron host), [`src/main.js`](https://github.com/blueturboguy07/ghost-location/blob/main/src/main.js) (Map and controls), [`backend/android.mjs`](https://github.com/blueturboguy07/ghost-location/blob/main/backend/android.mjs) (Android adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Location experience"]
  node_renderer["Map and controls<br/>[main.js]"]
  node_browser_map["Map tiles"]
  node_place_search["Place search<br/>[geocoder.mjs]"]
  node_route_planning["Road routing<br/>[routing.mjs]"]
end

subgraph group_desktop["Desktop coordination"]
  node_controller["Session controller<br/>[controller.mjs]"]
  node_electron["Electron host<br/>[main.mjs]"]
  node_onboarding["Device setup<br/>[main.js]"]
  node_session_recovery["Session recovery<br/>[controller.mjs]"]
end

subgraph group_devices["Phone adapters"]
  node_ios_adapter["iPhone adapter<br/>[ios.mjs]"]
  node_ios_bridge["iOS sidecar<br/>[ios_bridge.py]"]
  node_android_adapter["Android adapter<br/>[android.mjs]"]
  node_android_phone["Android phone tools"]
end

subgraph group_support["State and integrations"]
  node_saved_places[("Saved places<br/>[store.mjs]")]
  node_validation["Input validation<br/>[validation.mjs]"]
  node_process_runner["Process runner<br/>[process.mjs]"]
  node_network["Network discovery<br/>[network.mjs]"]
  node_telemetry["Usage telemetry"]
end

node_user(("User"))
node_osrm["OSRM service"]
node_photon["Photon service"]
node_phone(("Selected phone"))

node_user -->|"chooses location"| node_renderer
node_renderer -->|"displays tiles"| node_browser_map
node_renderer -.->|"searches places"| node_place_search
node_place_search -->|"queries"| node_photon
node_renderer -.->|"plans route"| node_route_planning
node_route_planning -->|"requests road route"| node_osrm
node_renderer -.->|"requests device action"| node_controller
node_electron -->|"creates controller"| node_controller
node_electron -->|"loads state"| node_saved_places
node_electron -->|"creates adapter"| node_ios_adapter
node_electron -->|"creates adapter"| node_android_adapter
node_electron -->|"uses discovery"| node_network
node_controller -->|"validates inputs"| node_validation
node_controller -->|"plans playback"| node_route_planning
node_controller -->|"manages sessions"| node_session_recovery
node_controller -.->|"controls iPhone"| node_ios_adapter
node_controller -.->|"controls Android"| node_android_adapter
node_ios_adapter -.->|"sends commands"| node_ios_bridge
node_android_adapter -->|"runs device tools"| node_process_runner
node_ios_adapter -.->|"simulates location"| node_phone
node_android_adapter -.->|"simulates location"| node_phone
node_android_adapter -.->|"uses helper runtime"| node_android_phone
node_user -->|"configures devices"| node_onboarding
node_electron -.->|"starts telemetry"| node_telemetry

click node_renderer "https://github.com/blueturboguy07/ghost-location/blob/main/src/main.js"
click node_place_search "https://github.com/blueturboguy07/ghost-location/blob/main/backend/geocoder.mjs"
click node_route_planning "https://github.com/blueturboguy07/ghost-location/blob/main/backend/routing.mjs"
click node_controller "https://github.com/blueturboguy07/ghost-location/blob/main/backend/controller.mjs"
click node_electron "https://github.com/blueturboguy07/ghost-location/blob/main/electron/main.mjs"
click node_onboarding "https://github.com/blueturboguy07/ghost-location/blob/main/src/main.js"
click node_session_recovery "https://github.com/blueturboguy07/ghost-location/blob/main/backend/controller.mjs"
click node_ios_adapter "https://github.com/blueturboguy07/ghost-location/blob/main/backend/ios.mjs"
click node_ios_bridge "https://github.com/blueturboguy07/ghost-location/blob/main/sidecar/ios_bridge.py"
click node_android_adapter "https://github.com/blueturboguy07/ghost-location/blob/main/backend/android.mjs"
click node_android_phone "https://github.com/blueturboguy07/ghost-location/tree/main/resources/android"
click node_saved_places "https://github.com/blueturboguy07/ghost-location/blob/main/backend/store.mjs"
click node_validation "https://github.com/blueturboguy07/ghost-location/blob/main/backend/validation.mjs"
click node_process_runner "https://github.com/blueturboguy07/ghost-location/blob/main/backend/process.mjs"
click node_network "https://github.com/blueturboguy07/ghost-location/blob/main/backend/network.mjs"
click node_telemetry "https://github.com/blueturboguy07/ghost-location/blob/main/electron/publik-telemetry.cjs"

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_renderer,node_browser_map,node_place_search,node_route_planning,node_user toneBlue
class node_controller,node_electron,node_onboarding,node_session_recovery toneAmber
class node_ios_adapter,node_ios_bridge,node_android_adapter,node_android_phone toneMint
class node_saved_places,node_validation,node_process_runner,node_network,node_telemetry toneRose
class node_osrm,node_photon,node_phone toneIndigo
```

## Components

### Location experience

- [Map and controls](https://github.com/blueturboguy07/ghost-location/blob/main/src/main.js): `src/main.js`
- **Map tiles**
- [Place search](https://github.com/blueturboguy07/ghost-location/blob/main/backend/geocoder.mjs): `backend/geocoder.mjs`
- [Road routing](https://github.com/blueturboguy07/ghost-location/blob/main/backend/routing.mjs): `backend/routing.mjs`

### Desktop coordination

- [Session controller](https://github.com/blueturboguy07/ghost-location/blob/main/backend/controller.mjs): `backend/controller.mjs`
- [Electron host](https://github.com/blueturboguy07/ghost-location/blob/main/electron/main.mjs): `electron/main.mjs`
- [Device setup](https://github.com/blueturboguy07/ghost-location/blob/main/src/main.js): `src/main.js`
- [Session recovery](https://github.com/blueturboguy07/ghost-location/blob/main/backend/controller.mjs): `backend/controller.mjs`

### Phone adapters

- [iPhone adapter](https://github.com/blueturboguy07/ghost-location/blob/main/backend/ios.mjs): `backend/ios.mjs`
- [iOS sidecar](https://github.com/blueturboguy07/ghost-location/blob/main/sidecar/ios_bridge.py): `sidecar/ios_bridge.py`
- [Android adapter](https://github.com/blueturboguy07/ghost-location/blob/main/backend/android.mjs): `backend/android.mjs`
- [Android phone tools](https://github.com/blueturboguy07/ghost-location/tree/main/resources/android): `resources/android`

### State and integrations

- [Saved places](https://github.com/blueturboguy07/ghost-location/blob/main/backend/store.mjs): `backend/store.mjs`
- [Input validation](https://github.com/blueturboguy07/ghost-location/blob/main/backend/validation.mjs): `backend/validation.mjs`
- [Process runner](https://github.com/blueturboguy07/ghost-location/blob/main/backend/process.mjs): `backend/process.mjs`
- [Network discovery](https://github.com/blueturboguy07/ghost-location/blob/main/backend/network.mjs): `backend/network.mjs`
- [Usage telemetry](https://github.com/blueturboguy07/ghost-location/blob/main/electron/publik-telemetry.cjs): `electron/publik-telemetry.cjs`

### Other components

- **User**
- **OSRM service**
- **Photon service**
- **Selected phone**

## Connections

- User → Map and controls: chooses location (evidence: `README.md`)
- Map and controls → Map tiles: displays tiles (evidence: `src/main.js`)
- Map and controls → Place search: searches places
- Place search → Photon service: queries (evidence: `backend/geocoder.mjs`)
- Map and controls → Road routing: plans route
- Road routing → OSRM service: requests road route (evidence: `backend/routing.mjs`)
- Map and controls → Session controller: requests device action
- Electron host → Session controller: creates controller (evidence: `electron/main.mjs`)
- Electron host → Saved places: loads state (evidence: `electron/main.mjs`)
- Electron host → iPhone adapter: creates adapter (evidence: `electron/main.mjs`)
- Electron host → Android adapter: creates adapter (evidence: `electron/main.mjs`)
- Electron host → Network discovery: uses discovery (evidence: `electron/main.mjs`)
- Session controller → Input validation: validates inputs (evidence: `backend/controller.mjs`)
- Session controller → Road routing: plans playback (evidence: `backend/controller.mjs`)
- Session controller → Session recovery: manages sessions (evidence: `README.md`)
- Session controller → iPhone adapter: controls iPhone
- Session controller → Android adapter: controls Android
- iPhone adapter → iOS sidecar: sends commands
- Android adapter → Process runner: runs device tools (evidence: `backend/android.mjs`)
- iPhone adapter → Selected phone: simulates location
- Android adapter → Selected phone: simulates location
- Android adapter → Android phone tools: uses helper runtime
- User → Device setup: configures devices (evidence: `README.md`)
- Electron host → Usage telemetry: starts telemetry (evidence: `electron/main.mjs`)