# masmaleki/laravel-geolocation architecture

> Architecture diagram of the GitHub repository masmaleki/laravel-geolocation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/masmaleki/laravel-geolocation
- Repository: https://github.com/masmaleki/laravel-geolocation

## Overview

##### Project type and purpose
- This is a Laravel “wrapper” package (composer library) that provides a Geo-location lookup service for IPs.
- It plugs into any Laravel 5.5+ app via Package Discovery, exposing a Facade, a Console Command, and a driver-based Lookup Manager.

##### File structure
Top-level:
- config/geolocation.php – default settings (provider, tokens)
- translations/… – localized country name maps
- src/GeoLocationServiceProvider.php – package bootstrapping & container bindings
- src/Console/GeoLocationCommand.php – artisan CLI integration
- src/Contracts/LookupInterface.php – driver contract
- src/Providers/IpInfo.php – provider implementation (HTTP call to ipinfo.io)
- src/GeoLocationManager.php – resolves & proxies requests to drivers
- src/GeoLocation.php – Facade / static API
- src/GeoLocationDetails.php – domain model for lookup results
- tests/… – PHPUnit coverage of each component

##### Extract architectural notes from README
- Single-driver for IpInfo today, with plans for MaxMind GeoIP2.
- Exposes a high-level API (Facade & Manager).
- Supports publishing config & translation files into a host app.

##### Main components & interactions
a. Client code (Laravel app) invokes `GeoLocation::lookup($ip)` or runs `artisan geolocation:lookup`.
b. The GeoLocation Facade resolves GeoLocationManager from the IoC container.
c. GeoLocationManager reads config (driver name & credentials).
d. It instantiates the appropriate LookupInterface driver (IpInfo) via ServiceProvider bindings.
e. The driver makes an HTTP request to ipinfo.io (external service).
f. Response JSON is mapped into a GeoLocationDetails object.
g. GeoLocationDetails can be used directly in app code or rendered by the Console Command.
h. Translations are loaded via Laravel’s translator when converting country codes to names.

##### Architectural patterns & principles
- Service Provider / IoC Container to bind interfaces → implementations.
- Facade pattern exposing static API.
- Manager / Factory pattern to resolve driver instances.
- Contract (LookupInterface) for extensibility (swap in MaxMind driver).
- Single Responsibility: Console command only handles CLI I/O, Manager handles driver resolution, Providers handle HTTP.
- Configuration & Translation publishing for customization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Package Boundary
    subgraph "Laravel GeoLocation Package"
        direction TB
        %% Config & Translations
        subgraph "Config & Translations"
            direction TB
            CFG["Config"]:::config
            EN["Translations EN"]:::config
            PT["Translations PT"]:::config
        end

        SP["Service Provider"]:::internal
        subgraph "Entry Points"
            direction TB
            F["GeoLocation Facade"]:::internal
            CMD["GeoLocation Command"]:::io
        end

        MGR["GeoLocationManager"]:::internal
        LKP["LookupInterface"]:::contract
        DRV["IpInfo Provider"]:::internal
        DM["GeoLocationDetails"]:::domain
    end

    %% External & Core
    SC["Service Container"]:::internal
    TR["Translator"]:::internal
    EXT["ipinfo.io API"]:::external
    APP["Laravel App Code"]:::internal

    %% Tests
    subgraph "Tests"
        direction TB
        T1["ConfigTest"]:::test
        T2["GeoLocationTest"]:::test
        T3["GeoLocationManagerTest"]:::test
        T4["GeoLocationDetailsTest"]:::test
        T5["IpInfoTest"]:::test
    end

    %% Relationships
    APP -->|"lookup() / artisan"| F
    APP -->|"artisan command"| CMD

    F -->|"resolves"| MGR
    MGR -->|"reads"| CFG
    MGR -->|"loads"| EN
    MGR -->|"loads"| PT

    SP -->|"binds"| SC
    SC -->|"provides"| MGR
    SC -->|"provides"| DRV

    MGR -->|"implements"| LKP
    MGR -->|"uses driver"| DRV

    DRV -->|"HTTP request"| EXT
    EXT -->|"JSON response"| DRV

    DRV -->|"maps to"| DM
    DM -->|"returns to"| MGR
    MGR -->|"returns details"| F
    DM -->|"renders"| CMD

    DM -->|"translates country"| TR
    TR -->|"data for"| DM

    %% Tests coverage relationships
    T1 --> CFG
    T2 --> F
    T3 --> MGR
    T4 --> DM
    T5 --> DRV

    %% Click events
    click CFG "https://github.com/masmaleki/laravel-geolocation/blob/master/config/geolocation.php"
    click EN "https://github.com/masmaleki/laravel-geolocation/blob/master/translations/en/countries.php"
    click PT "https://github.com/masmaleki/laravel-geolocation/blob/master/translations/pt_BR/countries.php"
    click SP "https://github.com/masmaleki/laravel-geolocation/blob/master/src/GeoLocationServiceProvider.php"
    click CMD "https://github.com/masmaleki/laravel-geolocation/blob/master/src/Console/GeoLocationCommand.php"
    click F "https://github.com/masmaleki/laravel-geolocation/blob/master/src/GeoLocation.php"
    click MGR "https://github.com/masmaleki/laravel-geolocation/blob/master/src/GeoLocationManager.php"
    click LKP "https://github.com/masmaleki/laravel-geolocation/blob/master/src/Contracts/LookupInterface.php"
    click DRV "https://github.com/masmaleki/laravel-geolocation/blob/master/src/Providers/IpInfo.php"
    click DM "https://github.com/masmaleki/laravel-geolocation/blob/master/src/GeoLocationDetails.php"
    click T1 "https://github.com/masmaleki/laravel-geolocation/blob/master/tests/ConfigTest.php"
    click T2 "https://github.com/masmaleki/laravel-geolocation/blob/master/tests/GeoLocationTest.php"
    click T3 "https://github.com/masmaleki/laravel-geolocation/blob/master/tests/GeoLocationManagerTest.php"
    click T4 "https://github.com/masmaleki/laravel-geolocation/blob/master/tests/GeoLocationDetailsTest.php"
    click T5 "https://github.com/masmaleki/laravel-geolocation/blob/master/tests/Providers/IpInfoTest.php"

    %% Styles
    classDef internal fill:#CFE2F3,stroke:#3A6EA5,color:#000
    classDef config fill:#D9EAD3,stroke:#6AA84F,color:#000
    classDef io fill:#F9CB9C,stroke:#E69138,color:#000
    classDef external fill:#E6E6E6,stroke:#A6A6A6,color:#000
    classDef contract fill:#D0A9F5,stroke:#8E44AD,color:#000
    classDef domain fill:#FFF2CC,stroke:#E6B800,color:#000
    classDef test fill:#F4CCCC,stroke:#CC0000,color:#000
```
