# junjunguo/pocketmaps architecture

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

- Interactive diagram: https://gitdiagram.com/junjunguo/pocketmaps
- Repository: https://github.com/junjunguo/pocketmaps

## Overview

PocketMaps is an Android offline-mapping app built around local map selection, map display, routing, and on-device navigation. Its documented capabilities also include map downloads, address and coordinate search, turn-by-turn directions, tracking and sport analysis, and importing/exporting data. The excerpts show activity launches, route calculation, settings state, and parts of download and export behavior; links for unsampled subsystems are therefore limited to documented product flow rather than presumed internal calls.

Main entry points: [`PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/MainActivity.java`](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/MainActivity.java) (Map selection), [`PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/MapHandler.java`](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/MapHandler.java) (Map and routing), [`PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/GeocodeActivity.java`](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/GeocodeActivity.java) (Address search), [`PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Tracking.java`](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Tracking.java) (Activity tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and maps"]
  node_main["Map selection<br/>[MainActivity.java]"]
  node_mapdownload["Map downloads"]
  node_mapunzip["Map installation"]
  node_mapactivity["Map screen<br/>[MapActivity.java]"]
  node_maphandler["Map and routing<br/>[MapHandler.java]"]
  node_maps["Local map files<br/>[MyMap.java]"]
end

subgraph group_route["Search and routing"]
  node_geocode["Address search"]
  node_localgeo["Local geocoder<br/>[GeocoderLocal.java]"]
  node_globalgeo["Global geocoder"]
  node_destination["Route destination<br/>[Destination.java]"]
end

subgraph group_track["Navigation and tracking"]
  node_navigator["Navigation control<br/>[Navigator.java]"]
  node_naviengine["Turn guidance<br/>[NaviEngine.java]"]
  node_tracking["Activity tracking<br/>[Tracking.java]"]
end

subgraph group_data["Persistence and transfer"]
  node_trackingdb[("Track records")]
  node_gpx["GPX export<br/>[GenerateGPX.java]"]
  node_export["Import and export"]
  node_unzip["Archive import<br/>[MapUnzip.java]"]
  node_bluetooth["Bluetooth transfer"]
  node_state[("App settings state<br/>[Variable.java]")]
end

node_user(("Map user"))
node_graphhopper["GraphHopper engine"]

node_user -->|"selects maps"| node_main
node_main -->|"opens map"| node_mapactivity
node_main -->|"opens downloads"| node_mapdownload
node_mapdownload -->|"installs maps"| node_mapunzip
node_mapactivity -->|"displays map"| node_maphandler
node_maphandler -->|"calculates route"| node_graphhopper
node_user -->|"searches address"| node_geocode
node_geocode -->|"queries local"| node_localgeo
node_geocode -.->|"queries global"| node_globalgeo
node_user -->|"starts guidance"| node_navigator
node_navigator -->|"controls guidance"| node_naviengine
node_user -->|"records activity"| node_tracking
node_tracking -->|"stores points"| node_trackingdb
node_tracking -->|"exports track"| node_gpx
node_user -->|"transfers data"| node_export
node_export -->|"imports archive"| node_unzip
node_export -->|"transmits data"| node_bluetooth
node_main -->|"uses settings"| node_state
node_maphandler -->|"uses local maps"| node_maps

click node_main "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/MainActivity.java"
click node_mapdownload "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/DownloadMapActivity.java"
click node_mapunzip "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/downloader/MapDownloadUnzip.java"
click node_mapactivity "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/MapActivity.java"
click node_maphandler "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/MapHandler.java"
click node_maps "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/model/MyMap.java"
click node_geocode "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/GeocodeActivity.java"
click node_localgeo "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/geocoding/GeocoderLocal.java"
click node_globalgeo "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/geocoding/GeocoderGlobal.java"
click node_destination "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Destination.java"
click node_navigator "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Navigator.java"
click node_naviengine "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/navigator/NaviEngine.java"
click node_tracking "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Tracking.java"
click node_trackingdb "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/db/DBtrackingPoints.java"
click node_gpx "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/util/GenerateGPX.java"
click node_export "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/ExportActivity.java"
click node_unzip "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/downloader/MapUnzip.java"
click node_bluetooth "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/bluetooth/BluetoothService.java"
click node_state "https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/util/Variable.java"

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_main,node_mapdownload,node_mapunzip,node_mapactivity,node_maphandler,node_maps,node_user toneBlue
class node_geocode,node_localgeo,node_globalgeo,node_destination toneAmber
class node_navigator,node_naviengine,node_tracking toneMint
class node_trackingdb,node_gpx,node_export,node_unzip,node_bluetooth,node_state toneRose
class node_graphhopper toneIndigo
```

## Components

### App and maps

- [Map selection](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/MainActivity.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/MainActivity.java`
- [Map downloads](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/DownloadMapActivity.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/DownloadMapActivity.java`
- [Map installation](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/downloader/MapDownloadUnzip.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/downloader/MapDownloadUnzip.java`
- [Map screen](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/MapActivity.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/MapActivity.java`
- [Map and routing](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/MapHandler.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/MapHandler.java`
- [Local map files](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/model/MyMap.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/model/MyMap.java`

### Search and routing

- [Address search](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/GeocodeActivity.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/GeocodeActivity.java`
- [Local geocoder](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/geocoding/GeocoderLocal.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/geocoding/GeocoderLocal.java`
- [Global geocoder](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/geocoding/GeocoderGlobal.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/geocoding/GeocoderGlobal.java`
- [Route destination](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Destination.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Destination.java`

### Navigation and tracking

- [Navigation control](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Navigator.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Navigator.java`
- [Turn guidance](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/navigator/NaviEngine.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/navigator/NaviEngine.java`
- [Activity tracking](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Tracking.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/map/Tracking.java`

### Persistence and transfer

- [Track records](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/db/DBtrackingPoints.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/db/DBtrackingPoints.java`
- [GPX export](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/util/GenerateGPX.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/util/GenerateGPX.java`
- [Import and export](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/ExportActivity.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/activities/ExportActivity.java`
- [Archive import](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/downloader/MapUnzip.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/downloader/MapUnzip.java`
- [Bluetooth transfer](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/bluetooth/BluetoothService.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/bluetooth/BluetoothService.java`
- [App settings state](https://github.com/junjunguo/pocketmaps/blob/master/PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/util/Variable.java): `PocketMaps/app/src/main/java/com/junjunguo/pocketmaps/util/Variable.java`

### Other components

- **Map user**
- **GraphHopper engine**

## Connections

- Map user → Map selection: selects maps
- Map selection → Map screen: opens map
- Map selection → Map downloads: opens downloads
- Map downloads → Map installation: installs maps
- Map screen → Map and routing: displays map
- Map and routing → GraphHopper engine: calculates route
- Map user → Address search: searches address
- Address search → Local geocoder: queries local
- Address search → Global geocoder: queries global
- Map user → Navigation control: starts guidance
- Navigation control → Turn guidance: controls guidance
- Map user → Activity tracking: records activity
- Activity tracking → Track records: stores points
- Activity tracking → GPX export: exports track
- Map user → Import and export: transfers data
- Import and export → Archive import: imports archive
- Import and export → Bluetooth transfer: transmits data
- Map selection → App settings state: uses settings
- Map and routing → Local map files: uses local maps