# reinmengelberg/conversionapi architecture

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

- Interactive diagram: https://gitdiagram.com/reinmengelberg/conversionapi
- Repository: https://github.com/reinmengelberg/conversionapi

## Overview

##### Project type and purpose
- This is a Matomo “ConversionApi” plugin, written in PHP, that intercepts Matomo visit data, enriches/transforms it, and forwards conversions to external advertising platforms (Google, Meta, LinkedIn) via their Conversion APIs.
- It integrates into the Matomo core as a plugin, exposing settings pages (Twig templates), controllers for API endpoints, scheduled tasks, and uses a set of services to authenticate, process, and send data.

##### File structure
- Top-level files:
- Controller.php, ConversionApi.php – entry points for web/API requests
- Tasks.php – cron tasks for asynchronous processing
- plugin.json, config/*.php – plugin metadata and configuration
- templates/*.twig – UI views for settings
- docs/ & screenshots/ – documentation
- Exceptions/, Settings/, Services/ – main PHP namespaces
- Services/ subdirectories:
- Auth – obtains OAuth tokens
- Processors – per-platform data formatting & API calls
- Visits – data retrieval, expansion, formatting, hashing
- ConversionApiManager – central orchestration service
- Settings/ defines typed configuration entities for API keys, consent, dimensions, events.

##### README
- Minimal README; plugin description and purpose are clear from file names and Matomo conventions.

##### Final advice
- Pipelines sequentially (VisitData → Expand → Format → Hash)
- Loops or retries for failed API calls (optional)
- Labels include both class names and responsibilities
- Don’t overthink—more granular components make the architecture clearer to maintain and extend.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Matomo Core
    subgraph "Matomo Core"
        CoreHost["Matomo Plugin Host"]:::core
        Scheduler["Cron Scheduler"]:::core
    end

    %% Plugin Components
    subgraph "ConversionApi Plugin"
        %% Controllers
        Controller["Controller.php"]:::plugin
        ConversionApiController["ConversionApi.php"]:::plugin

        %% Scheduled Tasks
        Tasks["Tasks.php"]:::plugin

        %% UI Templates
        subgraph "UI Templates"
            IndexTwig["index.twig"]:::plugin
            SiteApiTwig["siteApiSettings.twig"]:::plugin
            SiteConsentTwig["siteConsentSettings.twig"]:::plugin
            SiteDimensionsTwig["siteDimensionsSettings.twig"]:::plugin
            SiteEventTwig["siteEventSettings.twig"]:::plugin
        end

        %% Settings Entities
        subgraph "Settings Entities"
            ApiSettings["ApiSettings.php"]:::plugin
            ConsentSettings["ConsentSettings.php"]:::plugin
            DimensionSettings["DimensionSettings.php"]:::plugin
            EventSettings["EventSettings.php"]:::plugin
            MeasurableSettings["MeasurableSettings.php"]:::plugin
            Menu["Menu.php"]:::plugin
        end

        %% Exception Handling
        MissingConfigException["MissingConfigurationException.php"]:::plugin

        %% Configuration
        subgraph "Configuration"
            PluginJSON["plugin.json"]:::plugin
            ConfigConfig["config/config.php"]:::plugin
            ConfigTracker["config/tracker.php"]:::plugin
        end

        %% Documentation
        subgraph "Documentation"
            DocsIndex["docs/index.md"]:::plugin
            DocsFAQ["docs/faq.md"]:::plugin
            Screenshots["screenshots/.gitkeep"]:::plugin
        end

        %% Services
        subgraph "Services"
            ConversionApiManager["ConversionApiManager.php"]:::plugin

            subgraph "Auth Service"
                GoogleAuthService["GoogleAuthService.php"]:::plugin
            end

            subgraph "Platform Processors"
                GoogleProcessor["GoogleProcessor.php"]:::plugin
                MetaProcessor["MetaProcessor.php"]:::plugin
                LinkedinProcessor["LinkedinProcessor.php"]:::plugin
            end

            subgraph "Visit Data Pipeline"
                VisitDataService["VisitDataService.php"]:::plugin
                VisitExpandService["VisitExpandService.php"]:::plugin
                VisitFormatService["VisitFormatService.php"]:::plugin
                VisitHashService["VisitHashService.php"]:::plugin
            end
        end
    end

    %% Database and External Services
    DB[(Matomo MySQL DB)]:::db
    GoogleAPI["Google Conversion API"]:::external
    MetaAPI["Meta Conversion API"]:::external
    LinkedinAPI["LinkedIn Conversion API"]:::external

    %% Data Flows
    CoreHost -->|HTTP Request| Controller
    CoreHost -->|HTTP Request| ConversionApiController
    Controller -->|calls| ConversionApiManager
    ConversionApiController -->|calls| ConversionApiManager

    Scheduler -->|trigger| Tasks
    Tasks -->|enqueue/process| ConversionApiManager

    ConversionApiManager -->|fetch settings| ApiSettings
    ConversionApiManager -->|fetch settings| ConsentSettings
    ConversionApiManager -->|fetch settings| DimensionSettings
    ConversionApiManager -->|fetch settings| EventSettings
    ConversionApiManager -->|fetch settings| MeasurableSettings

    ApiSettings -->|persist| DB
    ConsentSettings -->|persist| DB
    DimensionSettings -->|persist| DB
    EventSettings -->|persist| DB
    MeasurableSettings -->|persist| DB

    Controller -->|render| IndexTwig
    Controller -->|render| SiteApiTwig
    Controller -->|render| SiteConsentTwig
    Controller -->|render| SiteDimensionsTwig
    Controller -->|render| SiteEventTwig

    ConversionApiManager -->|retrieve visits| VisitDataService
    VisitDataService -->|expand data| VisitExpandService
    VisitExpandService -->|format data| VisitFormatService
    VisitFormatService -->|hash data| VisitHashService
    VisitHashService -->|return data| ConversionApiManager

    ConversionApiManager -->|get token| GoogleAuthService
    GoogleAuthService -->|token| ConversionApiManager

    ConversionApiManager -->|send| GoogleProcessor
    ConversionApiManager -->|send| MetaProcessor
    ConversionApiManager -->|send| LinkedinProcessor

    GoogleProcessor -->|HTTP POST| GoogleAPI
    MetaProcessor -->|HTTP POST| MetaAPI
    LinkedinProcessor -->|HTTP POST| LinkedinAPI

    %% Exceptions
    ConversionApiManager -->|throw| MissingConfigException
    Controller -->|throw| MissingConfigException
    Tasks -->|throw| MissingConfigException

    %% Database
    VisitDataService -->|read| DB

    %% Click Events
    click Controller "https://github.com/reinmengelberg/conversionapi/blob/master/Controller.php"
    click ConversionApiController "https://github.com/reinmengelberg/conversionapi/blob/master/ConversionApi.php"
    click Tasks "https://github.com/reinmengelberg/conversionapi/blob/master/Tasks.php"
    click PluginJSON "https://github.com/reinmengelberg/conversionapi/blob/master/plugin.json"
    click ConfigConfig "https://github.com/reinmengelberg/conversionapi/blob/master/config/config.php"
    click ConfigTracker "https://github.com/reinmengelberg/conversionapi/blob/master/config/tracker.php"
    click IndexTwig "https://github.com/reinmengelberg/conversionapi/blob/master/templates/index.twig"
    click SiteApiTwig "https://github.com/reinmengelberg/conversionapi/blob/master/templates/siteApiSettings.twig"
    click SiteConsentTwig "https://github.com/reinmengelberg/conversionapi/blob/master/templates/siteConsentSettings.twig"
    click SiteDimensionsTwig "https://github.com/reinmengelberg/conversionapi/blob/master/templates/siteDimensionsSettings.twig"
    click SiteEventTwig "https://github.com/reinmengelberg/conversionapi/blob/master/templates/siteEventSettings.twig"
    click ApiSettings "https://github.com/reinmengelberg/conversionapi/blob/master/Settings/ApiSettings.php"
    click ConsentSettings "https://github.com/reinmengelberg/conversionapi/blob/master/Settings/ConsentSettings.php"
    click DimensionSettings "https://github.com/reinmengelberg/conversionapi/blob/master/Settings/DimensionSettings.php"
    click EventSettings "https://github.com/reinmengelberg/conversionapi/blob/master/Settings/EventSettings.php"
    click MeasurableSettings "https://github.com/reinmengelberg/conversionapi/blob/master/Settings/MeasurableSettings.php"
    click Menu "https://github.com/reinmengelberg/conversionapi/blob/master/Settings/Menu.php"
    click MissingConfigException "https://github.com/reinmengelberg/conversionapi/blob/master/Exceptions/MissingConfigurationException.php"
    click ConversionApiManager "https://github.com/reinmengelberg/conversionapi/blob/master/Services/ConversionApiManager.php"
    click GoogleAuthService "https://github.com/reinmengelberg/conversionapi/blob/master/Services/Auth/GoogleAuthService.php"
    click GoogleProcessor "https://github.com/reinmengelberg/conversionapi/blob/master/Services/Processors/GoogleProcessor.php"
    click MetaProcessor "https://github.com/reinmengelberg/conversionapi/blob/master/Services/Processors/MetaProcessor.php"
    click LinkedinProcessor "https://github.com/reinmengelberg/conversionapi/blob/master/Services/Processors/LinkedinProcessor.php"
    click VisitDataService "https://github.com/reinmengelberg/conversionapi/blob/master/Services/Visits/VisitDataService.php"
    click VisitExpandService "https://github.com/reinmengelberg/conversionapi/blob/master/Services/Visits/VisitExpandService.php"
    click VisitFormatService "https://github.com/reinmengelberg/conversionapi/blob/master/Services/Visits/VisitFormatService.php"
    click VisitHashService "https://github.com/reinmengelberg/conversionapi/blob/master/Services/Visits/VisitHashService.php"
    click DocsIndex "https://github.com/reinmengelberg/conversionapi/blob/master/docs/index.md"
    click DocsFAQ "https://github.com/reinmengelberg/conversionapi/blob/master/docs/faq.md"
    click Screenshots "https://github.com/reinmengelberg/conversionapi/blob/master/screenshots/.gitkeep"

    %% Styles
    classDef core fill:#DDDDDD,stroke:#888,stroke-width:1px
    classDef plugin fill:#AED6F1,stroke:#2980B9,stroke-width:1px
    classDef external fill:#ABEBC6,stroke:#27AE60,stroke-width:1px
    classDef db fill:#FADBD8,stroke:#C0392B,stroke-width:2px
```
