# vanilophp/framework architecture

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

- Interactive diagram: https://gitdiagram.com/vanilophp/framework
- Repository: https://github.com/vanilophp/framework

## Overview

##### Main components
- Core Framework/Infrastructure – At the root, you see build-tools, general configuration files, and several licensing and documentation files. These support the build and release processes.
- Modules – The src directory is subdivided into many domains. The key modules include:
- Adjustments: Handles discounts, fees, taxes, and other adjustments.
- Cart: Manages shopping carts, cart items, and state events.
- Category: Deals with product categorization and taxonomies.
- Channel: Manages sales channels and their settings.
- Checkout: Coordinates checkout processes using various drivers and store implementations.
- Contracts: Provides common interfaces and contracts used across modules.
- Foundation: Contains core business models and factories (e.g., Order, Customer, Shipment).
- Links: Likely provides functionalities to link related entities.
- MasterProduct: Manages master product records and variant handling.
- Order: Manages order creation, order items, and order status.
- Payment: Handles payment gateways, transactions, and payment events.
- Product: Manages product details, states, and attributes.
- Promotion: Responsible for coupon codes, discount rules, and promotion actions.
- Properties: Deals with additional properties that may be associated with products or other entities.
- Shipment: Manages shipping methods, shipping fee calculations, and shipment statuses.
- Support: Contains helper classes, DTOs (Data Transfer Objects), and shared traits.
- Taxes: Contains logic for tax calculation, rates, and tax categories.
- Each module further separates its logic into subdirectories such as Models, Providers (service providers for Laravel’s auto-discovery), Contracts/Interfaces, Tests, and Resources (often containing database migrations and configuration).

##### Relationships and interactions
- The Modules use a common Contracts layer (src/Contracts) to define interfaces. This allows interchangeable implementations and dependency inversion.
- Several modules publish or listen for events (for example, Cart and Order have their own event directories). This indicates a generally event-driven design where components signal state changes to others.
- The Foundation module holds core business entities that may be used across modules. Think of it as the central domain model repository that connects modules like Cart, Order, and Product.
- Payment, Checkout, and Order interact closely, as the checkout process leads to order creation and payment processing.
- Adjustments and Promotions influence cart totals and order pricing, suggesting dependencies from Cart and Order towards these modules.
- The Service Providers (found in each module’s Providers folder) register functionality with Laravel’s service container, which means the framework is using dependency injection and modular service registration to establish relationships.

##### Architectural patterns and design principles
- Modularization: Each domain is encapsulated within its own module. This is beneficial for maintenance, testing, and potential reuse.
- Contract-based design: Common interfaces/Contracts ensure that modules interact in a loosely-coupled manner.
- Event-driven patterns: The use of events and listeners (with directories like Events, Listeners, and Providers) indicate reactive design.
- Clear separation between core business logic and integration code (e.g., Service Providers, configuration files, migrations).

##### Technologies, frameworks, and libraries
- Laravel framework: The entire package is designed as a Laravel package compatible with Laravel versions 10.x and 11.x.
- Composer: For dependency management (as seen in composer.json files in modules).
- PHPUnit: For testing (phpunit.xml and extensive tests across modules).
- GitHub Workflows: CI/CD pipelines are present in .github directories managing tests and releases.
- Artisan and Eloquent: Although not explicitly in the file tree, service providers and models imply heavy use of Laravel’s built-in mechanisms.

##### Elements
- Core Infrastructure (Foundation, Contracts, Support).
- Domain-Specific Modules (Cart, Order, Payment, Product, etc.).
- Integration/Configuration layers (Service Providers, events, migrations, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform & Infrastructure
    subgraph "Platform & Infrastructure"
        CI["Core Infrastructure"]:::core
        CI2["Build Tools & CI/CD"]:::core
        Contracts["Contracts"]:::core
        Foundation["Foundation"]:::core
        Support["Support"]:::core
    end

    %% Domain Modules
    subgraph "Domain Modules"
        Adjustments["Adjustments"]:::domain
        Cart["Cart"]:::domain
        Category["Category"]:::domain
        Channel["Channel"]:::domain
        Checkout["Checkout"]:::domain
        Links["Links"]:::domain
        MasterProduct["MasterProduct"]:::domain
        Order["Order"]:::domain
        Payment["Payment"]:::domain
        Product["Product"]:::domain
        Promotion["Promotion"]:::domain
        Properties["Properties"]:::domain
        Shipment["Shipment"]:::domain
        Taxes["Taxes"]:::domain
    end

    %% Relationships between Platform & Infrastructure components
    CI2 -->|"supports"| CI
    CI -->|"registers"| Contracts
    CI -->|"provides"| Foundation
    CI -->|"includes"| Support

    %% Dependencies from Domain Modules to Core
    Cart -->|"DependsOn"| Foundation
    Order -->|"DependsOn"| Foundation
    Payment -->|"DependsOn"| Foundation
    Product -->|"DependsOn"| Foundation
    MasterProduct -->|"DependsOn"| Foundation
    Category -->|"DependsOn"| Foundation
    Channel -->|"DependsOn"| Foundation

    %% Domain Modules using common Contracts
    Cart -->|"Uses"| Contracts
    Order -->|"Uses"| Contracts
    Payment -->|"Uses"| Contracts
    Product -->|"Uses"| Contracts
    Promotion -->|"Uses"| Contracts
    Adjustments -->|"Uses"| Contracts
    Shipment -->|"Uses"| Contracts
    Taxes -->|"Uses"| Contracts

    %% Event-driven and functional interactions
    Cart -->|"Triggers"| Checkout
    Checkout -->|"Creates"| Order
    Checkout -->|"Initiates"| Payment
    Adjustments -->|"Modifies"| Order
    Promotion -->|"Modifies"| Order

    %% Class Definitions for color styling
    classDef core fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef domain fill:#aed6f1,stroke:#2874a6,stroke-width:2px;

    %% Click Events for Platform & Infrastructure components
    click CI "https://github.com/vanilophp/framework/tree/4.x/build-tools"
    click CI2 "https://github.com/vanilophp/framework/blob/4.x/.github"
    click Contracts "https://github.com/vanilophp/framework/tree/4.x/src/Contracts"
    click Foundation "https://github.com/vanilophp/framework/tree/4.x/src/Foundation"
    click Support "https://github.com/vanilophp/framework/tree/4.x/src/Support"

    %% Click Events for Domain Modules
    click Adjustments "https://github.com/vanilophp/framework/tree/4.x/src/Adjustments"
    click Cart "https://github.com/vanilophp/framework/tree/4.x/src/Cart"
    click Category "https://github.com/vanilophp/framework/tree/4.x/src/Category"
    click Channel "https://github.com/vanilophp/framework/tree/4.x/src/Channel"
    click Checkout "https://github.com/vanilophp/framework/tree/4.x/src/Checkout"
    click Links "https://github.com/vanilophp/framework/tree/4.x/src/Links"
    click MasterProduct "https://github.com/vanilophp/framework/tree/4.x/src/MasterProduct"
    click Order "https://github.com/vanilophp/framework/tree/4.x/src/Order"
    click Payment "https://github.com/vanilophp/framework/tree/4.x/src/Payment"
    click Product "https://github.com/vanilophp/framework/tree/4.x/src/Product"
    click Promotion "https://github.com/vanilophp/framework/tree/4.x/src/Promotion"
    click Properties "https://github.com/vanilophp/framework/tree/4.x/src/Properties"
    click Shipment "https://github.com/vanilophp/framework/tree/4.x/src/Shipment"
    click Taxes "https://github.com/vanilophp/framework/tree/4.x/src/Taxes"
```
