# dravasp/addressautocomplete architecture

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

- Interactive diagram: https://gitdiagram.com/dravasp/addressautocomplete
- Repository: https://github.com/dravasp/addressautocomplete

## Overview

##### Project Type and Purpose
- This is a Magento 2.4.x module (“Magento_AddressAutoComplete”) that extends the Magento checkout by adding address‐autocomplete functionality using the Google Places/Maps API.
- It plugs into the Magento dependency‐injection and layout systems, retrieves configuration from the admin interface, injects that config into the frontend as part of the checkout jsLayout, and then loads Google’s JavaScript API to power the autocomplete UI.

##### High‐Level Components
a. Magento 2 Core Platform
- ComponentRegistrar (registration.php)
- Dependency Injection Container (di.xml)
- CompositeConfigProvider (Magento\Checkout\Model\CompositeConfigProvider)
- Layout & View Layer (Knockout JS, PHTML templates)
- Admin Configuration Persistence (etc/config.xml → Magento’s system configuration DB tables)

b. AddressAutoComplete Module
- etc/module.xml – module declaration
- etc/di.xml – injects AutoCompleteConfigProvider into CompositeConfigProvider
- etc/config.xml – defines system-admin config fields (enabled, API key, geolocation, long postcode)
- etc/csp_whitelist.xml – allows loading Google domains under CSP
- Helper/Data.php – retrieves store‐scope config values from Magento’s ScopeConfig
- Model/AutoCompleteConfigProvider.php – implements ConfigProviderInterface and exposes config to window.checkoutConfig
- ViewModel/Autocomplete.php – optional PHP view model for template use
- view/frontend/layout/checkout_index_index.xml – adds the JS component to Magento’s checkout jsLayout
- view/frontend/web/js/autocomplete.js – frontend logic to load Google Maps API, instantiate autocomplete, handle place_changed events
- templates/address/autocomplete.phtml – simple input markup if needed

c. External Service
- Google Maps JavaScript API (Places library)

##### Relationships and Data Flows
1. Admin user sets module configuration in Magento admin (enabled, API key, etc.) → stored in Magento’s configuration tables.
2. On checkout page render:
a. Magento’s CompositeConfigProvider reads AutoCompleteConfigProvider (wired via etc/di.xml).
b. AutoCompleteConfigProvider calls Helper/Data to fetch each config value.
c. CompositeConfigProvider merges the module config into the global window.checkoutConfig JS object.
3. checkout_index_index.xml updates the checkout page’s jsLayout to include the Magento_AddressAutoComplete JS component.
4. At page load, autocomplete.js reads window.checkoutConfig.address_autocomplete.api_key → dynamically injects a <script> tag to load Google Maps API.
5. Google Maps API invokes initAutocomplete() callback → binds a Google Places Autocomplete instance to the address input field.
6. User selects address suggestion → the JS fillInAddress() handler populates Magento’s street_1, street_2 fields.
7. Rest of Magento checkout flow continues with the completed address.

##### Architectural Patterns & Principles
- MVC / MVVM: PHP Model (ConfigProvider), ViewModel (block arguments), Template (PHTML), JS View (Knockout/RequireJS component).
- Dependency Injection: etc/di.xml wiring the ConfigProvider into Magento’s CompositeConfigProvider.
- Configuration‐as‐Code: config.xml defines system configuration fields, csp_whitelist.xml enforces Content Security Policy.
- Progressive Enhancement: the module only loads JS if api_key is present and the module is enabled.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Backend (PHP Layer)
    subgraph "Backend (PHP Layer)"
        direction TB
        reg["registration.php"]:::php
        modXml["etc/module.xml"]:::php
        diXml["etc/di.xml"]:::php
        configXml["etc/config.xml"]:::php
        cspXml["etc/csp_whitelist.xml"]:::php
        adminUI["Admin UI (System Config)"]:::php
        configStore["Configuration Store (DB)"]:::db
        helper["Helper/Data.php"]:::php
        configProv["Model/AutoCompleteConfigProvider.php"]:::php
        composite["CompositeConfigProvider"]:::php
        viewModel["ViewModel/Autocomplete.php"]:::php
    end

    %% Frontend (JavaScript Layer)
    subgraph "Frontend (JS Layer)"
        direction TB
        layoutXml["view/frontend/layout/checkout_index_index.xml"]:::php
        checkoutConfig["window.checkoutConfig.address_autocomplete"]:::js
        autocompleteJS["view/frontend/web/js/autocomplete.js"]:::js
        template["templates/address/autocomplete.phtml"]:::php
        Input["DOM Input \"street_1\""]:::js
    end

    %% External Service
    subgraph "External Service"
        direction TB
        google["Google Maps/Places API"]:::ext
    end

    %% Data Flows
    adminUI -->|stores config| configStore
    configStore -->|fetched by| helper
    helper -->|provides config to| configProv
    diXml -->|injects ConfigProvider into| composite
    configProv -->|wired into| composite
    composite -->|merges into| checkoutConfig
    layoutXml -->|injects component into| checkoutConfig
    layoutXml -->|renders template| template
    checkoutConfig -->|read by| autocompleteJS
    autocompleteJS -->|loads script| google
    google -->|callback initAutocomplete| autocompleteJS
    autocompleteJS -->|fills form fields| Input

    %% Click Events
    click modXml "https://github.com/dravasp/addressautocomplete/blob/main/etc/module.xml"
    click diXml "https://github.com/dravasp/addressautocomplete/blob/main/etc/di.xml"
    click configXml "https://github.com/dravasp/addressautocomplete/blob/main/etc/config.xml"
    click cspXml "https://github.com/dravasp/addressautocomplete/blob/main/etc/csp_whitelist.xml"
    click reg "https://github.com/dravasp/addressautocomplete/blob/main/registration.php"
    click helper "https://github.com/dravasp/addressautocomplete/blob/main/Helper/Data.php"
    click configProv "https://github.com/dravasp/addressautocomplete/blob/main/Model/AutoCompleteConfigProvider.php"
    click viewModel "https://github.com/dravasp/addressautocomplete/blob/main/ViewModel/Autocomplete.php"
    click layoutXml "https://github.com/dravasp/addressautocomplete/blob/main/view/frontend/layout/checkout_index_index.xml"
    click autocompleteJS "https://github.com/dravasp/addressautocomplete/blob/main/view/frontend/web/js/autocomplete.js"
    click template "https://github.com/dravasp/addressautocomplete/blob/main/templates/address/autocomplete.phtml"

    %% Styles
    classDef php fill:#cde5f7,stroke:#225588,stroke-width:1px
    classDef js fill:#f7e9c2,stroke:#887722,stroke-width:1px
    classDef ext fill:#e2f7e2,stroke:#228822,stroke-width:1px,stroke-dasharray: 5 5
    classDef db fill:#f2e2f2,stroke:#882288,stroke-width:1px,shape:cylinder
```
