# mekos2772/ios-location-spoofer architecture

> Architecture diagram of the GitHub repository mekos2772/ios-location-spoofer, 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/mekos2772/ios-location-spoofer
- Repository: https://github.com/mekos2772/ios-location-spoofer

## Overview

This repository combines an iOS network-location spoofing module with an optional location-picker service. The main user workflow is to configure a target location, have a supported proxy intercept Apple’s WLOC response, and rewrite Wi-Fi and cell coordinates before iOS receives it. The picker offers Node and Cloudflare backends, plus token-based coordinate selection and administration. Edges reflect README statements and source-index references; some picker routes and platform wiring are documented but their full implementations were not sampled.

Main entry points: [`location-picker/server.js`](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/server.js) (Node picker API), [`location-picker/admin.js`](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/admin.js) (Admin API), [`location-picker/worker/src/index.js`](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/worker/src/index.js) (Worker picker API), [`location-spoofer.js`](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-spoofer.js) (Response rewriter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_spoof["Location rewriting"]
  node_platform_rules["Platform modules"]
  node_spoofer_core["Response rewriter"]
  node_spoofer_qx["Quantumult X rewriter"]
end

subgraph group_picker["Location picker"]
  node_map_ui["Map picker UI<br/>[server.js]"]
  node_node_api["Node picker API<br/>[server.js]"]
  node_sqlite[("Picker database<br/>[db.js]")]
  node_remote_config["Remote location config<br/>[server.js]"]
end

subgraph group_admin["Management"]
  node_admin_ui["Admin dashboard<br/>[admin-page.js]"]
  node_admin_api["Admin API<br/>[admin.js]"]
end

subgraph group_cloud["Cloudflare deployment"]
  node_worker_api["Worker picker API<br/>[index.js]"]
  node_worker_page["Worker map UI<br/>[page.js]"]
  node_webui_worker["Web UI Worker<br/>[worker.js]"]
  node_worker_kv[("Worker KV")]
end

node_user(("iPhone user"))
node_proxy["Proxy app"]
node_apple["Apple location service"]
node_picker_user(("Picker user"))
node_map_services["Map and geocoding"]

node_user -->|"configures"| node_proxy
node_proxy -->|"requests location"| node_apple
node_apple -->|"returns WLOC"| node_proxy
node_platform_rules -->|"configures interception"| node_proxy
node_proxy -->|"runs response script"| node_spoofer_core
node_proxy -->|"runs QX script"| node_spoofer_qx
node_spoofer_core -->|"returns rewritten response"| node_user
node_spoofer_qx -->|"returns rewritten response"| node_user
node_picker_user -->|"selects coordinates"| node_map_ui
node_map_ui -.->|"saves location"| node_node_api
node_node_api -->|"reads and writes"| node_sqlite
node_node_api -->|"serves config"| node_remote_config
node_remote_config -->|"provides coordinates"| node_spoofer_core
node_remote_config -->|"provides coordinates"| node_spoofer_qx
node_map_ui -->|"searches and fetches elevation"| node_map_services
node_admin_ui -->|"calls admin endpoints"| node_admin_api
node_admin_api -->|"serves dashboard"| node_admin_ui
node_node_api -->|"routes admin requests"| node_admin_api
node_admin_api -->|"manages tokens and logs"| node_sqlite
node_picker_user -->|"selects coordinates"| node_worker_page
node_worker_api -->|"serves page"| node_worker_page
node_worker_page -.->|"saves selection"| node_worker_api
node_worker_api -->|"reads and writes"| node_worker_kv
node_webui_worker -->|"bundles worker implementation"| node_worker_api

click node_platform_rules "https://github.com/mekos2772/ios-location-spoofer/blob/main/ios-location-spoofer.sgmodule"
click node_spoofer_core "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-spoofer.js"
click node_spoofer_qx "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-spoofer-qx.js"
click node_map_ui "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/server.js"
click node_node_api "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/server.js"
click node_worker_api "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/worker/src/index.js"
click node_worker_page "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/worker/src/page.js"
click node_webui_worker "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/cloudflare-webui/worker.js"
click node_sqlite "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/db.js"
click node_admin_ui "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/admin-page.js"
click node_admin_api "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/admin.js"
click node_remote_config "https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/server.js"

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_platform_rules,node_spoofer_core,node_spoofer_qx,node_user,node_picker_user toneBlue
class node_map_ui,node_node_api,node_sqlite,node_remote_config toneAmber
class node_admin_ui,node_admin_api toneMint
class node_worker_api,node_worker_page,node_webui_worker,node_worker_kv toneRose
class node_proxy,node_apple,node_map_services toneIndigo
```

## Components

### Location rewriting

- [Platform modules](https://github.com/mekos2772/ios-location-spoofer/blob/main/ios-location-spoofer.sgmodule): `ios-location-spoofer.sgmodule`
- [Response rewriter](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-spoofer.js): `location-spoofer.js`
- [Quantumult X rewriter](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-spoofer-qx.js): `location-spoofer-qx.js`

### Location picker

- [Map picker UI](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/server.js): `location-picker/server.js`
- [Node picker API](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/server.js): `location-picker/server.js`
- [Picker database](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/db.js): `location-picker/db.js`
- [Remote location config](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/server.js): `location-picker/server.js`

### Management

- [Admin dashboard](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/admin-page.js): `location-picker/admin-page.js`
- [Admin API](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/admin.js): `location-picker/admin.js`

### Cloudflare deployment

- [Worker picker API](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/worker/src/index.js): `location-picker/worker/src/index.js`
- [Worker map UI](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/worker/src/page.js): `location-picker/worker/src/page.js`
- [Web UI Worker](https://github.com/mekos2772/ios-location-spoofer/blob/main/location-picker/cloudflare-webui/worker.js): `location-picker/cloudflare-webui/worker.js`
- **Worker KV**

### Other components

- **iPhone user**
- **Proxy app**
- **Apple location service**
- **Picker user**
- **Map and geocoding**

## Connections

- iPhone user → Proxy app: configures (evidence: `README.md`)
- Proxy app → Apple location service: requests location (evidence: `README.md`)
- Apple location service → Proxy app: returns WLOC (evidence: `README.md`)
- Platform modules → Proxy app: configures interception (evidence: `README.md`)
- Proxy app → Response rewriter: runs response script (evidence: `README.md`)
- Proxy app → Quantumult X rewriter: runs QX script (evidence: `README.md`)
- Response rewriter → iPhone user: returns rewritten response (evidence: `README.md`)
- Quantumult X rewriter → iPhone user: returns rewritten response (evidence: `README.md`)
- Picker user → Map picker UI: selects coordinates (evidence: `README.md`)
- Map picker UI → Node picker API: saves location (evidence: `location-picker/server.js`)
- Node picker API → Picker database: reads and writes (evidence: `location-picker/server.js`)
- Node picker API → Remote location config: serves config (evidence: `README.md`)
- Remote location config → Response rewriter: provides coordinates (evidence: `README.md`)
- Remote location config → Quantumult X rewriter: provides coordinates (evidence: `README.md`)
- Map picker UI → Map and geocoding: searches and fetches elevation (evidence: `README.md`)
- Admin dashboard → Admin API: calls admin endpoints (evidence: `location-picker/admin-page.js`)
- Admin API → Admin dashboard: serves dashboard (evidence: `location-picker/admin.js`)
- Node picker API → Admin API: routes admin requests (evidence: `location-picker/server.js`)
- Admin API → Picker database: manages tokens and logs (evidence: `location-picker/admin.js`)
- Picker user → Worker map UI: selects coordinates
- Worker picker API → Worker map UI: serves page (evidence: `location-picker/worker/src/index.js`)
- Worker map UI → Worker picker API: saves selection (evidence: `location-picker/worker/src/index.js`)
- Worker picker API → Worker KV: reads and writes (evidence: `location-picker/worker/src/index.js`)
- Web UI Worker → Worker picker API: bundles worker implementation (evidence: `location-picker/cloudflare-webui/worker.js`)
