# isotope/core architecture

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

- Interactive diagram: https://gitdiagram.com/isotope/core
- Repository: https://github.com/isotope/core

## Overview

##### Project type and purpose
- This is an extension bundle for the Contao CMS, providing a full-fledged e-commerce solution (“Isotope eCommerce”) plus two add-on modules (“Isotope Reports” for analytics and “Isotope Rules” for pricing/promotions).
- It delivers both frontend storefront functionality (shopping cart, checkout steps, product lists) and backend administration (product management, orders, customers, configuration).

##### File structure
- Top-level: build scripts (composer.json, gulpfile.js, build.xml), project metadata.
- “system/modules/isotope”: the core extension, subdivided into:
- assets (JS/CSS/plugins)
- config (DI services.yaml, currencies, autoload)
- dca (Contao’s Data Container Arrays → metadata for backend forms)
- library (PHP namespaces for Controllers, Models, EventListeners, Services, Widgets)
- templates (HTML5 templates for frontend modules, backend overview pages)
- “system/modules/isotope_reports” and “system/modules/isotope_rules”: same pattern—assets, config, dca, library, templates.
- Supports DI (services.yaml, rector.php), event system, MVC, Contao’s module & DCA architecture.

##### README (docs/README.md)
- Likely describes system requirements, installation steps, high-level architecture: Contao core hooks into the extension via Contao Manager plugin, routes requests to Isotope’s controllers and templates.

##### Main components
a. Contao CMS core (HTTP kernel, Contao Manager, routing, DCA engine)
b. Isotope extension (split into sub‐components):
- Frontend controllers & modules (CheckoutStep, ContentElement, Module classes)
- Backend modules & DCA (BackendModule, Data Container Arrays, Callback classes)
- Core services (DependencyInjection, EventListeners, Automator, Analytics)
- Domain models & repositories (Isotope\Model\*, request cache, collections)
- Templates & assets (JS/CSS/plugins)
c. -ons:
- Reports module (Graphing libraries: d3, ApexCharts; Report services)
- Rules module (Pricing/discount model, rule engine)
d. Database (MySQL): stores product, order, customer, pricing, rule, report data
e. External services:
- Payment providers (Paypal, Stripe, others via Model\Payment\*)
- Shipping providers (flat rate, DHLBusiness, custom shipping Model\Shipping\*)
- Google Analytics (UnitedPrototype library)

##### Relationships and data flow
- Client (browser) → HTTP request → Contao kernel → routes to:
- Frontend page request → Isotope frontend Module/Controller → Services → Models → DB → Templates → back to client
- Backend request → Contao backend → Isotope BackendModule → DCA callbacks → Services → DB → backend templates
- Checkout workflow: front‐controller triggers CheckoutStep sequence → writes to ProductCollection (cart/order) → persists to DB → Payment service → external payment API callback (PostsaleController) → final update
- Rules engine invoked during price calculation (Model\ProductCollectionSurcharge → Rules module)
- Reports query data (via Report services) and feed charts (apexcharts, d3)

##### Architectural patterns and design principles
- MVC: Controllers (Isotope\Controller, Module classes) → Models (Isotope\Model\*) → Views (templates)
- Dependency Injection & service container (services.yaml, Compiler passes)
- Event-driven: EventListeners subscribe to price calculations, language changes, post-checkout tasks
- Modular design: core + optional sub-modules (reports, rules)
- Hook/callback extensibility (Contao DCA callbacks, ServiceAnnotation for hooks)

##### Elements
- HTTP request flow (browser → Contao → Isotope → DB → browser)
- Data persistence (controllers → models → DB)
- Events/callbacks (price calculation → rule engine)
- External API calls (payment/shipping/analytics)
- Gray for Contao core
- Blue for Isotope core
- Green for Reports add-on
- Orange for Rules add-on
- Red for external services
- Controllers (rectangles)
- Services and listeners (rounded rectangles)
- Models/repositories (parallelograms)
- Templates/assets (documents)

##### Summary
- Contao → Isotope core → DB → external dependencies
- Drill down into sub-components of the Isotope core (frontend vs. backend vs. services vs. models)
- Modular add-ons (reports, rules)
- Critical architectural elements (DI, event system, MVC layers, external integrations) are present to guide both design reviews and future enhancements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser"]:::external --> CK["Contao Kernel"]:::contao
    subgraph "Contao Core"
        CK
        CM["Contao Manager & Routing"]:::contao
        DCAE["DCA Engine"]:::contao
    end

    CK -->|"routes"| PC["PostsaleController"]:::isotope
    CK -->|"routes"| BM["Backend Modules"]:::isotope
    DCAE --> BM

    subgraph "Isotope Core"
        subgraph "Configuration & DI"
            SVC["services.yaml"]:::isotope
        end
        subgraph "Assets & Templates"
            ASSETS["Assets (JS/CSS)"]:::isotope
            TEMPL["Templates"]:::isotope
        end
        subgraph "Frontend"
            PC
            MOD1["Modules"]:::isotope
            MOD2["ContentElements"]:::isotope
            COOK["Checkout Steps"]:::isotope
        end
        subgraph "Backend"
            DCA["DCA Definitions"]:::isotope
            BM
        end
        subgraph "Services & EventListeners"
            EL["EventListeners"]:::isotope
            CP["RegisterHookListenersPass"]:::isotope
        end
        subgraph "Models & Repositories"
            DM["Domain Models & Repositories"]:::isotope
            PAYM["Payment Models"]:::isotope
            SHIPM["Shipping Models"]:::isotope
            GA["Google Analytics Lib"]:::external
        end
    end

    PC --> COOK
    PC --> DM
    COOK --> DM
    BM --> DCA
    PC --> ASSETS
    ASSETS --> TEMPL
    TEMPL --> Browser

    DM --> DB[(MySQL DB)]:::db
    PAYM --> PAYEXT["Payment Providers"]:::external
    SHIPM --> SHIPEXT["Shipping Providers"]:::external
    DM --> EL
    EL --> CP

    subgraph "Isotope Reports"
        R_ASSETS["Assets & Chart Libs"]:::reports
        R_CFG["Config"]:::reports
        R_SERV["Report Services"]:::reports
        R_BM["BackendModule Reports"]:::reports
        R_TPL["Templates"]:::reports
    end

    subgraph "Isotope Rules"
        RU_CFG1["Config"]:::rules
        RU_CFG2["DCA"]:::rules
        RU_BACK1["Backend Callbacks"]:::rules
        RU_BACK2["Rule Models"]:::rules
        RU_FE["Frontend Coupon Module"]:::rules
    end

    CP --> RU_CFG1
    CP --> R_CFG
    R_SERV --> R_BM
    R_BM --> R_TPL
    COOK --> RU_CFG2
    RU_BACK1 --> DM
    R_SERV --> DB
    RU_BACK2 --> DB
    DM --> GA

    click ASSETS "https://github.com/isotope/core/tree/2.9/system/modules/isotope/assets"
    click SVC "https://github.com/isotope/core/blob/2.9/system/modules/isotope/config/services.yaml"
    click DCA "https://github.com/isotope/core/tree/2.9/system/modules/isotope/dca"
    click PC "https://github.com/isotope/core/blob/2.9/system/modules/isotope/library/Isotope/Controller/PostsaleController.php"
    click MOD1 "https://github.com/isotope/core/tree/2.9/system/modules/isotope/library/Isotope/Module"
    click MOD2 "https://github.com/isotope/core/tree/2.9/system/modules/isotope/library/Isotope/ContentElement"
    click COOK "https://github.com/isotope/core/tree/2.9/system/modules/isotope/library/Isotope/CheckoutStep"
    click EL "https://github.com/isotope/core/tree/2.9/system/modules/isotope/library/Isotope/EventListener"
    click CP "https://github.com/isotope/core/blob/2.9/system/modules/isotope/library/Isotope/DependencyInjection/Compiler/RegisterHookListenersPass.php"
    click DM "https://github.com/isotope/core/tree/2.9/system/modules/isotope/library/Isotope/Model"
    click TEMPL "https://github.com/isotope/core/tree/2.9/system/modules/isotope/templates"
    click PAYM "https://github.com/isotope/core/tree/2.9/system/modules/isotope/library/Isotope/Model/Payment"
    click SHIPM "https://github.com/isotope/core/tree/2.9/system/modules/isotope/library/Isotope/Model/Shipping"
    click GA "https://github.com/isotope/core/tree/2.9/system/modules/isotope/library/UnitedPrototype/GoogleAnalytics"
    click R_ASSETS "https://github.com/isotope/core/tree/2.9/system/modules/isotope_reports/assets"
    click R_CFG "https://github.com/isotope/core/blob/2.9/system/modules/isotope_reports/config/config.php"
    click R_SERV "https://github.com/isotope/core/tree/2.9/system/modules/isotope_reports/library/Isotope/Report"
    click R_BM "https://github.com/isotope/core/blob/2.9/system/modules/isotope_reports/library/Isotope/BackendModule/Reports.php"
    click R_TPL "https://github.com/isotope/core/tree/2.9/system/modules/isotope_reports/templates"
    click RU_CFG1 "https://github.com/isotope/core/tree/2.9/system/modules/isotope_rules/config"
    click RU_CFG2 "https://github.com/isotope/core/tree/2.9/system/modules/isotope_rules/dca"
    click RU_BACK1 "https://github.com/isotope/core/blob/2.9/system/modules/isotope_rules/library/Isotope/Backend/Rule/Callback.php"
    click RU_BACK2 "https://github.com/isotope/core/blob/2.9/system/modules/isotope_rules/library/Isotope/Model/Rule.php"
    click RU_FE "https://github.com/isotope/core/blob/2.9/system/modules/isotope_rules/library/Isotope/Module/Coupons.php"

    classDef contao fill:#cccccc,stroke:#333,stroke-width:1px
    classDef isotope fill:#bfdbfe,stroke:#1e40af,stroke-width:1px
    classDef reports fill:#bbf7d0,stroke:#15803d,stroke-width:1px
    classDef rules fill:#fed7aa,stroke:#ea580c,stroke-width:1px
    classDef external fill:#fecaca,stroke:#b91c1c,stroke-width:1px
    classDef db fill:#ffffff,stroke:#000,stroke-width:2px,stroke-dasharray:5 5
```
