# onury/geolocator architecture

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

- Interactive diagram: https://gitdiagram.com/onury/geolocator
- Repository: https://github.com/onury/geolocator

## Overview

Geolocator.js is a browser-side geolocation utility. A caller invokes its API to obtain a location, optionally falling back from HTML5 geolocation to IP lookup, then can request address/timezone enrichment or mapping and other geographic services. The core also exposes watching, mobile lookup, distance and conversion utilities. The principal entry-point imports are visible in the source index; several feature implementations are unsampled, so their documented capabilities are shown without asserting unverified internal call paths.

Main entry points: [`src/core/geolocator.js`](https://github.com/onury/geolocator/blob/master/src/core/geolocator.js) (Geolocator API), [`src/lib/fetch.js`](https://github.com/onury/geolocator/blob/master/src/lib/fetch.js) (HTTP and JSONP), [`src/lib/utils.js`](https://github.com/onury/geolocator/blob/master/src/lib/utils.js) (Shared utilities), [`src/core/geo.helper.js`](https://github.com/onury/geolocator/blob/master/src/core/geo.helper.js) (Geo helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["Geolocator API<br/>[geolocator.js]"]
end

subgraph group_location["Location Acquisition"]
  node_html_geo["HTML5 geolocation"]
  node_watcher["Position watcher<br/>[geo.watcher.js]"]
  node_ip_lookup["IP location<br/>[geolocator.js]"]
  node_geojs_config["GeoJS source config<br/>[geojs.js]"]
  node_geoip_db["GeoIP DB source<br/>[geoip-db.js]"]
end

subgraph group_services["Geographic Services"]
  node_address["Geocoding lookup<br/>[geolocator.js]"]
  node_timezone["Timezone lookup<br/>[geolocator.js]"]
  node_distance_matrix["Distance and duration<br/>[geolocator.js]"]
  node_maps["Google Maps features<br/>[geolocator.js]"]
  node_mobile["Mobile location<br/>[geolocator.js]"]
  node_geo_utils["Geo calculations<br/>[geo.helper.js]"]
end

subgraph group_internal["Core Internals"]
  node_fetch["HTTP and JSONP<br/>[fetch.js]"]
  node_helpers["Geo helpers<br/>[geo.helper.js]"]
  node_errors["Geo errors<br/>[geo.error.js]"]
  node_utils["Shared utilities<br/>[utils.js]"]
  node_enums["Geo enumerations<br/>[enums.js]"]
end

node_caller(("Browser caller"))
node_geojs["GeoJS service"]
node_google_geo["Google geocoding"]

node_caller -->|"calls"| node_api
node_api -->|"locates with"| node_html_geo
node_api -->|"falls back to"| node_ip_lookup
node_api -->|"uses"| node_watcher
node_api -->|"requests"| node_address
node_api -->|"requests"| node_timezone
node_api -->|"provides"| node_distance_matrix
node_api -->|"creates"| node_maps
node_api -->|"locates by"| node_mobile
node_api -->|"calculates"| node_geo_utils
node_geojs_config -->|"configures"| node_geojs
node_ip_lookup -.->|"uses source"| node_geojs_config
node_ip_lookup -.->|"supports source"| node_geoip_db
node_ip_lookup -->|"requests via"| node_fetch
node_address -->|"uses"| node_google_geo
node_timezone -->|"uses"| node_google_geo
node_distance_matrix -->|"uses"| node_google_geo
node_maps -->|"loads APIs"| node_google_geo
node_api -->|"imports"| node_helpers
node_helpers -->|"imports"| node_fetch
node_api -->|"imports"| node_fetch
node_api -->|"imports"| node_errors
node_api -->|"imports"| node_utils
node_api -->|"imports"| node_enums
node_helpers -->|"imports"| node_enums
node_fetch -->|"imports"| node_utils
node_watcher -->|"imports"| node_utils
node_errors -->|"imports"| node_utils

click node_api "https://github.com/onury/geolocator/blob/master/src/core/geolocator.js"
click node_watcher "https://github.com/onury/geolocator/blob/master/src/core/geo.watcher.js"
click node_ip_lookup "https://github.com/onury/geolocator/blob/master/src/core/geolocator.js"
click node_geojs_config "https://github.com/onury/geolocator/blob/master/src/geo-ip-sources/geojs.js"
click node_geoip_db "https://github.com/onury/geolocator/blob/master/src/geo-ip-sources/geoip-db.js"
click node_address "https://github.com/onury/geolocator/blob/master/src/core/geolocator.js"
click node_timezone "https://github.com/onury/geolocator/blob/master/src/core/geolocator.js"
click node_distance_matrix "https://github.com/onury/geolocator/blob/master/src/core/geolocator.js"
click node_maps "https://github.com/onury/geolocator/blob/master/src/core/geolocator.js"
click node_mobile "https://github.com/onury/geolocator/blob/master/src/core/geolocator.js"
click node_geo_utils "https://github.com/onury/geolocator/blob/master/src/core/geo.helper.js"
click node_fetch "https://github.com/onury/geolocator/blob/master/src/lib/fetch.js"
click node_helpers "https://github.com/onury/geolocator/blob/master/src/core/geo.helper.js"
click node_errors "https://github.com/onury/geolocator/blob/master/src/core/geo.error.js"
click node_utils "https://github.com/onury/geolocator/blob/master/src/lib/utils.js"
click node_enums "https://github.com/onury/geolocator/blob/master/src/core/enums.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_api,node_caller toneBlue
class node_html_geo,node_watcher,node_ip_lookup,node_geojs_config,node_geoip_db toneAmber
class node_address,node_timezone,node_distance_matrix,node_maps,node_mobile,node_geo_utils toneMint
class node_fetch,node_helpers,node_errors,node_utils,node_enums toneRose
class node_geojs,node_google_geo toneIndigo
```

## Components

### Public API

- [Geolocator API](https://github.com/onury/geolocator/blob/master/src/core/geolocator.js): `src/core/geolocator.js`

### Location Acquisition

- **HTML5 geolocation**
- [Position watcher](https://github.com/onury/geolocator/blob/master/src/core/geo.watcher.js): `src/core/geo.watcher.js`
- [IP location](https://github.com/onury/geolocator/blob/master/src/core/geolocator.js): `src/core/geolocator.js`
- [GeoJS source config](https://github.com/onury/geolocator/blob/master/src/geo-ip-sources/geojs.js): `src/geo-ip-sources/geojs.js`
- [GeoIP DB source](https://github.com/onury/geolocator/blob/master/src/geo-ip-sources/geoip-db.js): `src/geo-ip-sources/geoip-db.js`

### Geographic Services

- [Geocoding lookup](https://github.com/onury/geolocator/blob/master/src/core/geolocator.js): `src/core/geolocator.js`
- [Timezone lookup](https://github.com/onury/geolocator/blob/master/src/core/geolocator.js): `src/core/geolocator.js`
- [Distance and duration](https://github.com/onury/geolocator/blob/master/src/core/geolocator.js): `src/core/geolocator.js`
- [Google Maps features](https://github.com/onury/geolocator/blob/master/src/core/geolocator.js): `src/core/geolocator.js`
- [Mobile location](https://github.com/onury/geolocator/blob/master/src/core/geolocator.js): `src/core/geolocator.js`
- [Geo calculations](https://github.com/onury/geolocator/blob/master/src/core/geo.helper.js): `src/core/geo.helper.js`

### Core Internals

- [HTTP and JSONP](https://github.com/onury/geolocator/blob/master/src/lib/fetch.js): `src/lib/fetch.js`
- [Geo helpers](https://github.com/onury/geolocator/blob/master/src/core/geo.helper.js): `src/core/geo.helper.js`
- [Geo errors](https://github.com/onury/geolocator/blob/master/src/core/geo.error.js): `src/core/geo.error.js`
- [Shared utilities](https://github.com/onury/geolocator/blob/master/src/lib/utils.js): `src/lib/utils.js`
- [Geo enumerations](https://github.com/onury/geolocator/blob/master/src/core/enums.js): `src/core/enums.js`

### Other components

- **Browser caller**
- **GeoJS service**
- **Google geocoding**

## Connections

- Browser caller → Geolocator API: calls (evidence: `README.md`)
- Geolocator API → HTML5 geolocation: locates with (evidence: `README.md`)
- Geolocator API → IP location: falls back to (evidence: `README.md`)
- Geolocator API → Position watcher: uses (evidence: `src/core/geolocator.js`)
- Geolocator API → Geocoding lookup: requests (evidence: `README.md`)
- Geolocator API → Timezone lookup: requests (evidence: `README.md`)
- Geolocator API → Distance and duration: provides (evidence: `README.md`)
- Geolocator API → Google Maps features: creates (evidence: `README.md`)
- Geolocator API → Mobile location: locates by (evidence: `README.md`)
- Geolocator API → Geo calculations: calculates (evidence: `README.md`)
- GeoJS source config → GeoJS service: configures (evidence: `src/geo-ip-sources/geojs.js`)
- IP location → GeoJS source config: uses source
- IP location → GeoIP DB source: supports source
- IP location → HTTP and JSONP: requests via (evidence: `src/core/geolocator.js`)
- Geocoding lookup → Google geocoding: uses (evidence: `README.md`)
- Timezone lookup → Google geocoding: uses (evidence: `README.md`)
- Distance and duration → Google geocoding: uses (evidence: `README.md`)
- Google Maps features → Google geocoding: loads APIs (evidence: `README.md`)
- Geolocator API → Geo helpers: imports (evidence: `src/core/geolocator.js`)
- Geo helpers → HTTP and JSONP: imports (evidence: `src/core/geo.helper.js`)
- Geolocator API → HTTP and JSONP: imports (evidence: `src/core/geolocator.js`)
- Geolocator API → Geo errors: imports (evidence: `src/core/geolocator.js`)
- Geolocator API → Shared utilities: imports (evidence: `src/core/geolocator.js`)
- Geolocator API → Geo enumerations: imports (evidence: `src/core/geolocator.js`)
- Geo helpers → Geo enumerations: imports (evidence: `src/core/geo.helper.js`)
- HTTP and JSONP → Shared utilities: imports (evidence: `src/lib/fetch.js`)
- Position watcher → Shared utilities: imports (evidence: `src/core/geo.watcher.js`)
- Geo errors → Shared utilities: imports (evidence: `src/core/geo.error.js`)
