# stevebauman/location architecture

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

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

## Overview

Location is a Laravel package that resolves an IP address into a normalized Position using configurable online or local providers. The main workflow is application lookup → facade/manager → request construction and driver selection → provider lookup (with fallbacks) → Position. It also supports MaxMind database updates and shared-storage caching, Cloudflare request-header geolocation, and a fake for application testing. Some provider and request-adapter internals were not excerpted; their grouping and links are limited to README or SOURCE INDEX evidence.

Main entry points: [`src/LocationManager.php`](https://github.com/stevebauman/location/blob/master/src/LocationManager.php) (Location manager), [`src/Drivers/Driver.php`](https://github.com/stevebauman/location/blob/master/src/Drivers/Driver.php) (Driver fallback chain), [`src/Facades/Location.php`](https://github.com/stevebauman/location/blob/master/src/Facades/Location.php) (Location facade), [`src/Drivers/MaxMind.php`](https://github.com/stevebauman/location/blob/master/src/Drivers/MaxMind.php) (MaxMind lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Lookup entry"]
  node_facade["Location facade<br/>[Location.php]"]
end

subgraph group_routing["Lookup orchestration"]
  node_manager["Location manager"]
  node_request["Location request"]
  node_request_contract["Request contract<br/>[Request.php]"]
  node_deadline["Lookup deadline<br/>[Deadline.php]"]
  node_driver["Driver fallback chain<br/>[Driver.php]"]
  node_position["Position result<br/>[Position.php]"]
end

subgraph group_providers["Location providers"]
  node_http["HTTP driver base<br/>[HttpDriver.php]"]
  node_http_providers["HTTP geolocation providers"]
  node_cloudflare["Cloudflare headers<br/>[Cloudflare.php]"]
end

subgraph group_maxmind["MaxMind data"]
  node_maxmind["MaxMind lookup<br/>[MaxMind.php]"]
  node_local_db[("Local database cache")]
  node_update["Database update command<br/>[Update.php]"]
end

subgraph group_support["Package support"]
  node_fake["Location fake<br/>[LocationFake.php]"]
  node_provider["Service provider"]
end

node_app(("Laravel application"))
node_external_apis{{"Geolocation APIs"}}

node_app -->|"requests lookup"| node_facade
node_facade -->|"resolves to"| node_manager
node_manager -->|"builds request"| node_request
node_manager -->|"limits lookup"| node_deadline
node_manager -->|"dispatches lookup"| node_driver
node_request -->|"implements"| node_request_contract
node_driver -->|"uses for HTTP"| node_http
node_driver -.->|"runs fallback"| node_maxmind
node_http -->|"requests geolocation"| node_external_apis
node_http_providers -.->|"extends base"| node_http
node_cloudflare -->|"reads headers"| node_request_contract
node_maxmind -->|"reads database"| node_local_db
node_maxmind -->|"hydrates result"| node_position
node_driver -->|"creates result"| node_position
node_facade -->|"installs fake"| node_fake
node_provider -->|"registers singleton"| node_manager
node_provider -->|"binds cache"| node_local_db
node_update -->|"gets drivers"| node_facade
node_update -.->|"updates database"| node_maxmind

click node_facade "https://github.com/stevebauman/location/blob/master/src/Facades/Location.php"
click node_manager "https://github.com/stevebauman/location/blob/master/src/LocationManager.php"
click node_request "https://github.com/stevebauman/location/blob/master/src/LocationRequest.php"
click node_request_contract "https://github.com/stevebauman/location/blob/master/src/Request.php"
click node_deadline "https://github.com/stevebauman/location/blob/master/src/Deadline.php"
click node_driver "https://github.com/stevebauman/location/blob/master/src/Drivers/Driver.php"
click node_http "https://github.com/stevebauman/location/blob/master/src/Drivers/HttpDriver.php"
click node_http_providers "https://github.com/stevebauman/location/tree/master/src/Drivers"
click node_cloudflare "https://github.com/stevebauman/location/blob/master/src/Drivers/Cloudflare.php"
click node_maxmind "https://github.com/stevebauman/location/blob/master/src/Drivers/MaxMind.php"
click node_local_db "https://github.com/stevebauman/location/blob/master/src/Drivers/LocalMaxMindDatabase.php"
click node_position "https://github.com/stevebauman/location/blob/master/src/Position.php"
click node_fake "https://github.com/stevebauman/location/blob/master/src/LocationFake.php"
click node_provider "https://github.com/stevebauman/location/blob/master/src/LocationServiceProvider.php"
click node_update "https://github.com/stevebauman/location/blob/master/src/Commands/Update.php"

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_facade toneBlue
class node_manager,node_request,node_request_contract,node_deadline,node_driver,node_position toneAmber
class node_http,node_http_providers,node_cloudflare,node_external_apis toneMint
class node_maxmind,node_local_db,node_update toneRose
class node_fake,node_provider,node_app toneIndigo
```

## Components

### Lookup entry

- [Location facade](https://github.com/stevebauman/location/blob/master/src/Facades/Location.php): `src/Facades/Location.php`

### Lookup orchestration

- [Location manager](https://github.com/stevebauman/location/blob/master/src/LocationManager.php): `src/LocationManager.php`
- [Location request](https://github.com/stevebauman/location/blob/master/src/LocationRequest.php): `src/LocationRequest.php`
- [Request contract](https://github.com/stevebauman/location/blob/master/src/Request.php): `src/Request.php`
- [Lookup deadline](https://github.com/stevebauman/location/blob/master/src/Deadline.php): `src/Deadline.php`
- [Driver fallback chain](https://github.com/stevebauman/location/blob/master/src/Drivers/Driver.php): `src/Drivers/Driver.php`
- [Position result](https://github.com/stevebauman/location/blob/master/src/Position.php): `src/Position.php`

### Location providers

- [HTTP driver base](https://github.com/stevebauman/location/blob/master/src/Drivers/HttpDriver.php): `src/Drivers/HttpDriver.php`
- [HTTP geolocation providers](https://github.com/stevebauman/location/tree/master/src/Drivers): `src/Drivers`
- [Cloudflare headers](https://github.com/stevebauman/location/blob/master/src/Drivers/Cloudflare.php): `src/Drivers/Cloudflare.php`

### MaxMind data

- [MaxMind lookup](https://github.com/stevebauman/location/blob/master/src/Drivers/MaxMind.php): `src/Drivers/MaxMind.php`
- [Local database cache](https://github.com/stevebauman/location/blob/master/src/Drivers/LocalMaxMindDatabase.php): `src/Drivers/LocalMaxMindDatabase.php`
- [Database update command](https://github.com/stevebauman/location/blob/master/src/Commands/Update.php): `src/Commands/Update.php`

### Package support

- [Location fake](https://github.com/stevebauman/location/blob/master/src/LocationFake.php): `src/LocationFake.php`
- [Service provider](https://github.com/stevebauman/location/blob/master/src/LocationServiceProvider.php): `src/LocationServiceProvider.php`

### Other components

- **Laravel application**
- **Geolocation APIs**

## Connections

- Laravel application → Location facade: requests lookup (evidence: `readme.md`)
- Location facade → Location manager: resolves to (evidence: `src/Facades/Location.php`)
- Location manager → Location request: builds request (evidence: `src/LocationManager.php`)
- Location manager → Lookup deadline: limits lookup (evidence: `src/LocationManager.php`)
- Location manager → Driver fallback chain: dispatches lookup (evidence: `src/LocationManager.php`)
- Location request → Request contract: implements (evidence: `src/LocationRequest.php`)
- Driver fallback chain → HTTP driver base: uses for HTTP (evidence: `src/Drivers/HttpDriver.php`)
- Driver fallback chain → MaxMind lookup: runs fallback (evidence: `src/Drivers/MaxMind.php`)
- HTTP driver base → Geolocation APIs: requests geolocation (evidence: `src/Drivers/HttpDriver.php`)
- HTTP geolocation providers → HTTP driver base: extends base (evidence: `src/Drivers/Ip2locationio.php`)
- Cloudflare headers → Request contract: reads headers (evidence: `src/Drivers/Cloudflare.php`)
- MaxMind lookup → Local database cache: reads database (evidence: `src/Drivers/MaxMind.php`)
- MaxMind lookup → Position result: hydrates result (evidence: `src/Drivers/MaxMind.php`)
- Driver fallback chain → Position result: creates result (evidence: `src/Drivers/Driver.php`)
- Location facade → Location fake: installs fake (evidence: `src/Facades/Location.php`)
- Service provider → Location manager: registers singleton (evidence: `src/LocationServiceProvider.php`)
- Service provider → Local database cache: binds cache (evidence: `src/LocationServiceProvider.php`)
- Database update command → Location facade: gets drivers (evidence: `src/Commands/Update.php`)
- Database update command → MaxMind lookup: updates database
