# mhkh22/geo-sleuth architecture

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

- Interactive diagram: https://gitdiagram.com/mhkh22/geo-sleuth
- Repository: https://github.com/mhkh22/geo-sleuth
- Video tour (about a minute): https://gitdiagram.com/mhkh22/geo-sleuth/video

## Overview

geo-sleuth is an agent skill for geolocating a photo and producing an evidence-backed camera position, heading, confidence, and satellite image. The agent reads the skill instructions and runs focused Python commands: inspect the image and clues, search candidate regions and sites, compare terrain or street-view imagery, refine the camera pose, and document the result. Scripts rank candidates while the agent judges them. The README describes this workflow and major capabilities; source-index references support the cited internal links, but unsampled script behavior is not assumed.

Main entry points: [`skills/geo-sleuth/scripts/_image.py`](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_image.py) (Image utilities), [`skills/geo-sleuth/scripts/geo.py`](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/geo.py) (Geo calculations), [`skills/geo-sleuth/scripts/_net.py`](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_net.py) (Network utilities), [`skills/geo-sleuth/scripts/match.py`](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/match.py) (Image matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Agent workflow"]
  node_skill["Skill instructions<br/>[SKILL.md]"]
  node_board[("Candidate board<br/>[board.py]")]
end

subgraph group_clues["Photo clues"]
  node_intake["Photo intake<br/>[intake.py]"]
  node_exif["EXIF clues<br/>[exif.py]"]
  node_ocr["Text recognition<br/>[ocr.py]"]
  node_cluescript["Clue lookup<br/>[clues.py]"]
end

subgraph group_search["Geographic search"]
  node_regions["Region packs<br/>[regions.py]"]
  node_osm["OSM search<br/>[osm.py]"]
  node_gazetteer["Gazetteer search<br/>[gazetteer.py]"]
  node_poi["POI search<br/>[poi.py]"]
  node_terrain["Terrain scan<br/>[terrain.py]"]
  node_refresh["Data refresh<br/>[refresh.py]"]
end

subgraph group_verify["Candidate verification"]
  node_match["Image matching<br/>[match.py]"]
  node_gsv["Google Street View<br/>[gsv.py]"]
  node_baidu["Baidu panoramas<br/>[baidu_pano.py]"]
  node_sat["Satellite scan<br/>[sat_scan.py]"]
  node_pose["Camera pose<br/>[pose.py]"]
  node_sun["Sun geometry<br/>[sun.py]"]
  node_evidence["Evidence output<br/>[evidence.py]"]
  node_tiles["Satellite tiles<br/>[tiles.py]"]
end

subgraph group_shared["Shared services"]
  node_geo["Geo calculations<br/>[geo.py]"]
  node_image["Image utilities<br/>[_image.py]"]
  node_net["Network utilities<br/>[_net.py]"]
  node_browser["Browser helper<br/>[_browser.py]"]
  node_device["Device helper<br/>[_device.py]"]
end

node_agent(("Geolocation agent"))

node_agent -->|"reads instructions"| node_skill
node_agent -->|"runs scripts"| node_intake
node_agent -->|"runs scripts"| node_exif
node_agent -->|"records candidates"| node_board
node_agent -->|"scans terrain"| node_terrain
node_agent -->|"ranks images"| node_match
node_agent -->|"refines position"| node_pose
node_agent -->|"produces evidence"| node_evidence
node_intake -->|"reads images"| node_image
node_exif -->|"reads images"| node_image
node_ocr -->|"reads images"| node_image
node_cluescript -->|"uses region data"| node_regions
node_osm -->|"uses region data"| node_regions
node_gazetteer -->|"uses region data"| node_regions
node_poi -->|"uses region data"| node_regions
node_board -->|"resolves regions"| node_regions
node_terrain -->|"uses calculations"| node_geo
node_terrain -->|"uses image tools"| node_image
node_match -->|"reads images"| node_image
node_match -->|"renders candidates"| node_gsv
node_match -->|"renders candidates"| node_baidu
node_gsv -->|"uses China service"| node_baidu
node_gsv -->|"converts coordinates"| node_geo
node_baidu -->|"converts coordinates"| node_geo
node_osm -->|"fetches map data"| node_net
node_terrain -->|"fetches elevation"| node_net
node_tiles -->|"fetches tiles"| node_net
node_tiles -->|"converts coordinates"| node_geo
node_sun -->|"uses tile data"| node_tiles
node_evidence -->|"uses image tools"| node_image
node_evidence -->|"uses satellite maps"| node_tiles
node_evidence -->|"uses calculations"| node_geo
node_sat -->|"uses satellite tiles"| node_tiles
node_sat -->|"uses calculations"| node_geo
node_pose -->|"reads images"| node_image
node_baidu -->|"fetches panoramas"| node_net
node_browser -->|"uses network helper"| node_net
node_refresh -->|"fetches sources"| node_net
node_match -->|"selects compute"| node_device

click node_skill "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/SKILL.md"
click node_intake "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/intake.py"
click node_exif "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/exif.py"
click node_ocr "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/ocr.py"
click node_cluescript "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/clues.py"
click node_regions "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/regions.py"
click node_osm "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/osm.py"
click node_gazetteer "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/gazetteer.py"
click node_poi "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/poi.py"
click node_terrain "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/terrain.py"
click node_board "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/board.py"
click node_match "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/match.py"
click node_gsv "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/gsv.py"
click node_baidu "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/baidu_pano.py"
click node_sat "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/sat_scan.py"
click node_pose "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/pose.py"
click node_sun "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/sun.py"
click node_evidence "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/evidence.py"
click node_tiles "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/tiles.py"
click node_geo "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/geo.py"
click node_image "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_image.py"
click node_net "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_net.py"
click node_browser "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_browser.py"
click node_device "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_device.py"
click node_refresh "https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/refresh.py"

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_skill,node_board toneBlue
class node_intake,node_exif,node_ocr,node_cluescript toneAmber
class node_regions,node_osm,node_gazetteer,node_poi,node_terrain,node_refresh toneMint
class node_match,node_gsv,node_baidu,node_sat,node_pose,node_sun,node_evidence,node_tiles toneRose
class node_geo,node_image,node_net,node_browser,node_device,node_agent toneIndigo
```

## Components

### Agent workflow

- [Skill instructions](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/SKILL.md): `skills/geo-sleuth/SKILL.md`
- [Candidate board](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/board.py): `skills/geo-sleuth/scripts/board.py`

### Photo clues

- [Photo intake](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/intake.py): `skills/geo-sleuth/scripts/intake.py`
- [EXIF clues](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/exif.py): `skills/geo-sleuth/scripts/exif.py`
- [Text recognition](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/ocr.py): `skills/geo-sleuth/scripts/ocr.py`
- [Clue lookup](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/clues.py): `skills/geo-sleuth/scripts/clues.py`

### Geographic search

- [Region packs](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/regions.py): `skills/geo-sleuth/scripts/regions.py`
- [OSM search](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/osm.py): `skills/geo-sleuth/scripts/osm.py`
- [Gazetteer search](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/gazetteer.py): `skills/geo-sleuth/scripts/gazetteer.py`
- [POI search](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/poi.py): `skills/geo-sleuth/scripts/poi.py`
- [Terrain scan](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/terrain.py): `skills/geo-sleuth/scripts/terrain.py`
- [Data refresh](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/refresh.py): `skills/geo-sleuth/scripts/refresh.py`

### Candidate verification

- [Image matching](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/match.py): `skills/geo-sleuth/scripts/match.py`
- [Google Street View](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/gsv.py): `skills/geo-sleuth/scripts/gsv.py`
- [Baidu panoramas](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/baidu_pano.py): `skills/geo-sleuth/scripts/baidu_pano.py`
- [Satellite scan](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/sat_scan.py): `skills/geo-sleuth/scripts/sat_scan.py`
- [Camera pose](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/pose.py): `skills/geo-sleuth/scripts/pose.py`
- [Sun geometry](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/sun.py): `skills/geo-sleuth/scripts/sun.py`
- [Evidence output](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/evidence.py): `skills/geo-sleuth/scripts/evidence.py`
- [Satellite tiles](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/tiles.py): `skills/geo-sleuth/scripts/tiles.py`

### Shared services

- [Geo calculations](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/geo.py): `skills/geo-sleuth/scripts/geo.py`
- [Image utilities](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_image.py): `skills/geo-sleuth/scripts/_image.py`
- [Network utilities](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_net.py): `skills/geo-sleuth/scripts/_net.py`
- [Browser helper](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_browser.py): `skills/geo-sleuth/scripts/_browser.py`
- [Device helper](https://github.com/mhkh22/geo-sleuth/blob/main/skills/geo-sleuth/scripts/_device.py): `skills/geo-sleuth/scripts/_device.py`

### Other components

- **Geolocation agent**

## Connections

- Geolocation agent → Skill instructions: reads instructions (evidence: `README.md`)
- Geolocation agent → Photo intake: runs scripts (evidence: `README.md`)
- Geolocation agent → EXIF clues: runs scripts (evidence: `README.md`)
- Geolocation agent → Candidate board: records candidates (evidence: `README.md`)
- Geolocation agent → Terrain scan: scans terrain (evidence: `README.md`)
- Geolocation agent → Image matching: ranks images (evidence: `README.md`)
- Geolocation agent → Camera pose: refines position (evidence: `README.md`)
- Geolocation agent → Evidence output: produces evidence (evidence: `README.md`)
- Photo intake → Image utilities: reads images (evidence: `skills/geo-sleuth/scripts/intake.py`)
- EXIF clues → Image utilities: reads images (evidence: `skills/geo-sleuth/scripts/exif.py`)
- Text recognition → Image utilities: reads images (evidence: `skills/geo-sleuth/scripts/ocr.py`)
- Clue lookup → Region packs: uses region data (evidence: `skills/geo-sleuth/scripts/clues.py`)
- OSM search → Region packs: uses region data (evidence: `skills/geo-sleuth/scripts/osm.py`)
- Gazetteer search → Region packs: uses region data (evidence: `skills/geo-sleuth/scripts/gazetteer.py`)
- POI search → Region packs: uses region data (evidence: `skills/geo-sleuth/scripts/poi.py`)
- Candidate board → Region packs: resolves regions (evidence: `skills/geo-sleuth/scripts/board.py`)
- Terrain scan → Geo calculations: uses calculations (evidence: `skills/geo-sleuth/scripts/terrain.py`)
- Terrain scan → Image utilities: uses image tools (evidence: `skills/geo-sleuth/scripts/terrain.py`)
- Image matching → Image utilities: reads images (evidence: `skills/geo-sleuth/scripts/match.py`)
- Image matching → Google Street View: renders candidates (evidence: `skills/geo-sleuth/scripts/match.py`)
- Image matching → Baidu panoramas: renders candidates (evidence: `skills/geo-sleuth/scripts/match.py`)
- Google Street View → Baidu panoramas: uses China service (evidence: `skills/geo-sleuth/scripts/gsv.py`)
- Google Street View → Geo calculations: converts coordinates (evidence: `skills/geo-sleuth/scripts/gsv.py`)
- Baidu panoramas → Geo calculations: converts coordinates (evidence: `skills/geo-sleuth/scripts/baidu_pano.py`)
- OSM search → Network utilities: fetches map data (evidence: `skills/geo-sleuth/scripts/osm.py`)
- Terrain scan → Network utilities: fetches elevation (evidence: `skills/geo-sleuth/scripts/terrain.py`)
- Satellite tiles → Network utilities: fetches tiles (evidence: `skills/geo-sleuth/scripts/tiles.py`)
- Satellite tiles → Geo calculations: converts coordinates (evidence: `skills/geo-sleuth/scripts/tiles.py`)
- Sun geometry → Satellite tiles: uses tile data (evidence: `skills/geo-sleuth/scripts/sun.py`)
- Evidence output → Image utilities: uses image tools (evidence: `skills/geo-sleuth/scripts/evidence.py`)
- Evidence output → Satellite tiles: uses satellite maps (evidence: `skills/geo-sleuth/scripts/evidence.py`)
- Evidence output → Geo calculations: uses calculations (evidence: `skills/geo-sleuth/scripts/evidence.py`)
- Satellite scan → Satellite tiles: uses satellite tiles (evidence: `skills/geo-sleuth/scripts/sat_scan.py`)
- Satellite scan → Geo calculations: uses calculations (evidence: `skills/geo-sleuth/scripts/sat_scan.py`)
- Camera pose → Image utilities: reads images (evidence: `skills/geo-sleuth/scripts/pose.py`)
- Baidu panoramas → Network utilities: fetches panoramas (evidence: `skills/geo-sleuth/scripts/baidu_pano.py`)
- Browser helper → Network utilities: uses network helper (evidence: `skills/geo-sleuth/scripts/_browser.py`)
- Data refresh → Network utilities: fetches sources (evidence: `skills/geo-sleuth/scripts/refresh.py`)
- Image matching → Device helper: selects compute (evidence: `skills/geo-sleuth/scripts/match.py`)
