# alexreisner/geocoder architecture

> Architecture diagram of the GitHub repository alexreisner/geocoder, 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/alexreisner/geocoder
- Repository: https://github.com/alexreisner/geocoder

## Overview

Geocoder is a Ruby geocoding library: users submit addresses, coordinates, or IPs; the library selects a lookup service, returns normalized results, and can integrate geocoding and spatial queries with application models. The graph also captures caching, request-IP lookup, command-line use, and database-backed queries. Provider adapters and result classes are represented as families to avoid cataloguing dozens of individual services. Relationships involving unsampled modules are omitted or marked unverified; documented capabilities are identified with README evidence.

Main entry points: [`lib/geocoder/stores/active_record.rb`](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/stores/active_record.rb) (ActiveRecord scopes), [`lib/geocoder.rb`](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder.rb) (Geocoder search), [`lib/geocoder/lookups`](https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/lookups) (Provider adapters), [`lib/geocoder/lookup.rb`](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/lookup.rb) (Lookup dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Search and Results"]
  node_entry["Geocoder search<br/>[geocoder.rb]"]
  node_query["Query classification<br/>[query.rb]"]
  node_lookup["Lookup dispatch<br/>[lookup.rb]"]
end

subgraph group_providers["Lookup Providers"]
  node_provider_adapters["Provider adapters"]
  node_result_types["Provider results"]
end

subgraph group_models["Models and Queries"]
  node_calculations["Geo calculations<br/>[calculations.rb]"]
  node_model_callbacks["Model geocoding"]
  node_active_record_store["ActiveRecord scopes<br/>[active_record.rb]"]
  node_sql["Spatial SQL<br/>[sql.rb]"]
end

subgraph group_support["Configuration and Support"]
  node_configuration["Lookup configuration<br/>[configuration.rb]"]
  node_cache["Lookup cache<br/>[cache.rb]"]
  node_cache_stores["Cache backends"]
  node_request["Request IP lookup<br/>[request.rb]"]
  node_cli["Command line<br/>[cli.rb]"]
end

node_user(("Application user"))
node_external_apis{{"Geocoding APIs"}}
node_database[("Application database")]
node_rack_request(("HTTP request"))

node_user -->|"submits query"| node_entry
node_entry -.->|"creates query"| node_query
node_query -->|"selects lookup"| node_lookup
node_lookup -.->|"dispatches to"| node_provider_adapters
node_provider_adapters -.->|"requests geocoding"| node_external_apis
node_provider_adapters -.->|"normalizes results"| node_result_types
node_result_types -->|"returns location data"| node_user
node_user -->|"configures geocoding"| node_model_callbacks
node_model_callbacks -->|"stores coordinates"| node_database
node_user -->|"runs spatial queries"| node_active_record_store
node_active_record_store -->|"computes query geometry"| node_calculations
node_active_record_store -->|"builds spatial SQL"| node_sql
node_active_record_store -->|"queries records"| node_database
node_configuration -.->|"configures services"| node_lookup
node_entry -.->|"uses caching"| node_cache
node_cache -.->|"uses backend"| node_cache_stores
node_rack_request -->|"provides client IP"| node_request
node_request -->|"looks up IP"| node_entry
node_user -.->|"runs lookup"| node_cli

click node_entry "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder.rb"
click node_query "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/query.rb"
click node_lookup "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/lookup.rb"
click node_provider_adapters "https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/lookups"
click node_result_types "https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/results"
click node_calculations "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/calculations.rb"
click node_model_callbacks "https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/models"
click node_active_record_store "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/stores/active_record.rb"
click node_sql "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/sql.rb"
click node_configuration "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/configuration.rb"
click node_cache "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/cache.rb"
click node_cache_stores "https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/cache_stores"
click node_request "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/request.rb"
click node_cli "https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/cli.rb"

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_entry,node_query,node_lookup,node_user toneBlue
class node_provider_adapters,node_result_types,node_database toneAmber
class node_calculations,node_model_callbacks,node_active_record_store,node_sql,node_external_apis,node_rack_request toneMint
class node_configuration,node_cache,node_cache_stores,node_request,node_cli toneRose
```

## Components

### Search and Results

- [Geocoder search](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder.rb): `lib/geocoder.rb`
- [Query classification](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/query.rb): `lib/geocoder/query.rb`
- [Lookup dispatch](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/lookup.rb): `lib/geocoder/lookup.rb`

### Lookup Providers

- [Provider adapters](https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/lookups): `lib/geocoder/lookups`
- [Provider results](https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/results): `lib/geocoder/results`

### Models and Queries

- [Geo calculations](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/calculations.rb): `lib/geocoder/calculations.rb`
- [Model geocoding](https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/models): `lib/geocoder/models`
- [ActiveRecord scopes](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/stores/active_record.rb): `lib/geocoder/stores/active_record.rb`
- [Spatial SQL](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/sql.rb): `lib/geocoder/sql.rb`

### Configuration and Support

- [Lookup configuration](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/configuration.rb): `lib/geocoder/configuration.rb`
- [Lookup cache](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/cache.rb): `lib/geocoder/cache.rb`
- [Cache backends](https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/cache_stores): `lib/geocoder/cache_stores`
- [Request IP lookup](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/request.rb): `lib/geocoder/request.rb`
- [Command line](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/cli.rb): `lib/geocoder/cli.rb`

### Other components

- **Application user**
- **Geocoding APIs**
- **Application database**
- **HTTP request**

## Connections

- Application user → Geocoder search: submits query
- Geocoder search → Query classification: creates query
- Query classification → Lookup dispatch: selects lookup (evidence: `lib/geocoder/query.rb`)
- Lookup dispatch → Provider adapters: dispatches to
- Provider adapters → Geocoding APIs: requests geocoding
- Provider adapters → Provider results: normalizes results
- Provider results → Application user: returns location data
- Application user → Model geocoding: configures geocoding
- Model geocoding → Application database: stores coordinates
- Application user → ActiveRecord scopes: runs spatial queries
- ActiveRecord scopes → Geo calculations: computes query geometry (evidence: `lib/geocoder/stores/active_record.rb`)
- ActiveRecord scopes → Spatial SQL: builds spatial SQL (evidence: `lib/geocoder/stores/active_record.rb`)
- ActiveRecord scopes → Application database: queries records
- Lookup configuration → Lookup dispatch: configures services
- Geocoder search → Lookup cache: uses caching
- Lookup cache → Cache backends: uses backend
- HTTP request → Request IP lookup: provides client IP
- Request IP lookup → Geocoder search: looks up IP
- Application user → Command line: runs lookup
