# vaened/php-price-engine architecture

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

- Interactive diagram: https://gitdiagram.com/vaened/php-price-engine
- Repository: https://github.com/vaened/php-price-engine

## Overview

##### Main Components
- Price Engine Core – The library’s entry point and configuration elements (e.g., PriceEngineConfig, helper classes).
- Cashier Abstraction – The core interface with two concrete implementations:
- SimpleCashier (operating on a gross price concept)
- RegularCashier (operating on unit-price + taxes)
- Adjustments and Handlers – All the classes inside the “Adjustments” directory form the “adjustment” layer. These include:
- Adjustment base classes and various specific adjustments (Charge, Discount).
- Taxation adjustments, split into Inclusive and Exclusive (with related error handling, e.g., InvalidTaxEncoding).
- The “Handlers” folder holds classes (ExclusiveAdjustmentHandler, InclusiveAdjustmentHandler) responsible for applying these adjustments.
- Monetary Types – Classes that encapsulate money and amount details:
- Money (e.g., Amount, Price, NonTaxableItem, Taxable, etc.)
- Additional Supporting Classes – Such as Modifier, Helper, Cacheable concerns, and utility classes in tests to represent codes and summaries.

##### Relationships and Interactions
- An external client creates an Amount (using either taxable or taxexempt approaches) that wraps a monetary value (via the Brick\Money library).
- The client then creates a Cashier (either Simple or Regular) using that Amount along with configuration of taxes (inclusive or exclusive), discounts, and charges.
- The Cashier coordinates between:
- Its internal adjustment mechanism (using adjusted classes from “Adjustments” and “Handlers”) to apply calculations.
- The Money components that represent prices.
- Adjustments (taxes, discounts, charges) are applied to the financial value based on the structure defined in the adjustment layers.
- After operations (like updating quantity, applying discounts, adding charges), the Cashier produces a Summary with subtotal, total, and possibly individual tax/charge/discount computations.

##### Architectural Patterns and Design Principles
- Modularity and Separation of Concerns – The project is organized into clearly defined layers (domain logic in “src” with separate namespaces for Money, Cashiers, Adjustments, and Handlers).
- Extensibility – The design offers extension points. For instance, new “cashier” implementations can extend the base Cashier, and new types of adjustments can be integrated.
- Domain-Driven Design – The use of clear domain concepts (such as Amount, TaxCodes, Discounts, Charges) aids in encapsulating business rules.

##### Relevant Technologies/Frameworks
- PHP – The main programming language.
- Composer – For dependency management (as indicated in composer.json).
- Brick\Money – An external library used to handle precise monetary calculations.
- PHPUnit – For running tests (supported by the phpunit.xml and tests directory).
- Docker – A Dockerfile is provided, to help containerize or run the library in controlled environments.
- GitHub Actions – Workflow configuration (.github/workflows/tests.yml) to automate builds and tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Client Input
    subgraph "Client Input"
        A["Input/Amount Creator"]:::input
    end

    %% Subgraph: Money Domain
    subgraph "Money Domain"
        B["Amount"]:::money
        C["Taxable/NonTaxable Items"]:::money
        D["Price Representation"]:::money
    end

    %% Subgraph: Price Engine Core
    subgraph "Price Engine Core"
        E["PriceEngineConfig"]:::core
        F["Helper"]:::core
        G["Modifier"]:::core
        U["Modifiers Container"]:::core
    end

    %% Subgraph: Cashier Layer
    subgraph "Cashier Layer"
        H["Base Cashier"]:::cashier
        I["SimpleCashier"]:::cashier
        J["RegularCashier"]:::cashier
    end

    %% Subgraph: Adjustments & Handlers
    subgraph "Adjustments & Handlers"
        subgraph "Adjustments"
            K["Adjustment Base"]:::adjustment
            L["Charge Adjustment"]:::adjustment
            M["Discount Adjustment"]:::adjustment
            subgraph "Taxation Adjustments"
                N["Exclusive Tax"]:::adjustment
                O["Inclusive Tax"]:::adjustment
                P["InvalidTaxEncoding"]:::adjustment
            end
        end
        subgraph "Handlers"
            Q["ExclusiveAdjustmentHandler"]:::handler
            R["InclusiveAdjustmentHandler"]:::handler
        end
    end

    %% Subgraph: Utilities
    subgraph "Utilities"
        T["Cacheable"]:::utilities
    end

    %% Subgraph: Summary
    subgraph "Summary"
        S["Computation Summary"]:::summary
    end

    %% Data Flow
    A -->|"creates"| B
    B -->|"supplies_monetary_data"| H
    E -->|"configures"| H
    F -->|"provides_utils"| H
    G -->|"modifies_data"| H
    U -->|"provides_modifiers"| H
    H -->|"selects_type"| I
    H -->|"selects_type"| J
    I -->|"applies_adjustments"| K
    J -->|"applies_adjustments"| K
    K -->|"calculates_charge"| L
    K -->|"calculates_discount"| M
    K -->|"applies_exclusive_tax"| N
    K -->|"applies_inclusive_tax"| O
    K -->|"handles_errors"| P
    N -->|"handled_by"| Q
    O -->|"handled_by"| R
    Q -->|"updates_price"| D
    R -->|"updates_price"| D
    D -->|"finalizes_summary"| S
    C -->|"updates_values"| S
    E -->|"uses_caching"| T

    %% Styles
    classDef input fill:#f5f5dc,stroke:#000,stroke-width:1px;
    classDef money fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef core fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef cashier fill:#ffcccb,stroke:#000,stroke-width:1px;
    classDef adjustment fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef handler fill:#dda0dd,stroke:#000,stroke-width:1px;
    classDef utilities fill:#e6e6fa,stroke:#000,stroke-width:1px;
    classDef summary fill:#fffacd,stroke:#000,stroke-width:1px;

    %% Click Events for Price Engine Core
    click E "https://github.com/vaened/php-price-engine/blob/master/src/PriceEngineConfig.php"
    click F "https://github.com/vaened/php-price-engine/blob/master/src/Helper.php"
    click G "https://github.com/vaened/php-price-engine/blob/master/src/Modifier.php"
    click U "https://github.com/vaened/php-price-engine/blob/master/src/Modifiers.php"

    %% Click Events for Cashier Abstraction
    click H "https://github.com/vaened/php-price-engine/blob/master/src/Cashier.php"
    click I "https://github.com/vaened/php-price-engine/blob/master/src/Cashiers/SimpleCashier.php"
    click J "https://github.com/vaened/php-price-engine/blob/master/src/Cashiers/RegularCashier.php"

    %% Click Events for Adjustments and Handlers
    click K "https://github.com/vaened/php-price-engine/blob/master/src/Adjustments/Adjustment.php"
    click L "https://github.com/vaened/php-price-engine/blob/master/src/Adjustments/Charge.php"
    click M "https://github.com/vaened/php-price-engine/blob/master/src/Adjustments/Discount.php"
    click N "https://github.com/vaened/php-price-engine/blob/master/src/Adjustments/Taxation/Exclusive.php"
    click O "https://github.com/vaened/php-price-engine/blob/master/src/Adjustments/Taxation/Inclusive.php"
    click P "https://github.com/vaened/php-price-engine/blob/master/src/Adjustments/Taxation/InvalidTaxEncoding.php"
    click Q "https://github.com/vaened/php-price-engine/blob/master/src/Handlers/ExclusiveAdjustmentHandler.php"
    click R "https://github.com/vaened/php-price-engine/blob/master/src/Handlers/InclusiveAdjustmentHandler.php"

    %% Click Events for Monetary Types
    click B "https://github.com/vaened/php-price-engine/blob/master/src/Money/Amount.php"
    click C "https://github.com/vaened/php-price-engine/blob/master/src/Money/Taxable.php"
    click D "https://github.com/vaened/php-price-engine/blob/master/src/Price.php"

    %% Click Events for Supporting Classes and Utilities
    click T "https://github.com/vaened/php-price-engine/blob/master/src/Concerns/Cacheable.php"
    click S "https://github.com/vaened/php-price-engine/blob/master/src/Summary.php"
```
