# inklabs/kommerce-core architecture

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

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

## Overview

##### Main Components
- Action Layer (Use Cases): Representing “Commands” and “Queries” that serve as the entry points into the system. These are used to drive the application’s use cases. Display the CommandBusInterface and QueryBusInterface as the core dispatchers that route actions.
- Action Handlers: Separate handlers (grouped by domain, e.g., “Cart”, “Product”, “Order”, “Coupon”, etc.) that process incoming Commands and Queries. They coordinate with other system components.
- Domain Entities: “Plain” PHP objects that encapsulate business logic. These include classes such as Product, Cart, Order, Tag, etc. They hold business behavior and relationships.
- Data Transfer Objects (EntityDTO): Used to flatten the complex object graphs held by Entities into a format suitable for presentation. Emphasize the use of DTO Builders for creating these objects.
- Domain Events and Event Dispatcher: Show how Domain Events (e.g., PasswordChangedEvent or OrderCreatedFromCartEvent) are raised by Entities and later dispatched by services through an event dispatcher.
- Infrastructure/Lib Layer:
- Utility classes (e.g., Mapper, Uuid classes, Authorization, etc.).
- Command and Query Buses (that are responsible for action dispatching).
- Payment Gateway and Shipment Gateway integrations.
- Other utility support elements like the FileManager, XMLSerializer, and pricing utilities.

##### Relationships and Data Flows
- Directional data flow from the Action layer (Commands/Queries) that are dispatched via the CommandBus/QueryBus.
- Flow from actions to the corresponding Action Handlers which then interact with Domain Entities and Domain Services.
- Flow of Data Transfer Objects being built by DTO Builders from Entities so that view templates (or any presentation layer) can use a clean, flattened data structure.

##### Architectural Patterns and Design Principles
- CQRS pattern: clearly separate the Command path (which does not return a value but may result in side effects) from the Query path (which constructs DTOs and returns data).
- “Domain Event” mechanism that decouples state changes in Entities from subsequent system reactions.
- “Separation of Concerns” and “Dependency Inversion” principles by showing how the Action Handlers, Domain Services, Repositories, and Infrastructure interact strictly via well-defined interfaces.
- With “SOLID” indicators where each module is responsible for its specific concern.

##### Relevant Technologies and Frameworks
- PHP/Composer for dependency management.
- Doctrine 2 ORM for entity persistence (reference the mapping files in “config/” and “src/Doctrine/Mapping”).
- PHPUnit (as found under “tests/”) for TDD.
- Adherence to PSR-2 and PSR-4 in naming and auto-loading.
- External Payment and Shipment Gateways (e.g., StripeFake, EasyPostGateway).

##### Recap for the Principal Software Engineer
- How Action Handlers invoke Domain Entities and Services.
- How the Repository layer abstracts persistence (using Doctrine ORM) and how Entities are built into DTOs for presentation.
- Domain Events mechanism that decouples state changes from reactive processes.
- Be very detailed: capture all major interactions without oversimplification—each architectural layer should be clearly segregated while showing its interaction points with other layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        A1["Entry Point"]
        A2["Commands/Queries (src/Action)"]:::app
        A3["Command Bus (src/Lib/Command)"]:::app
        A4["Query Bus (src/Lib/Query)"]:::app
    end
    A1 -->|"sendAction"| A2
    A2 -->|"dispatchTo"| A3
    A2 -->|"dispatchTo"| A4

    %% Action Handlers
    subgraph "Action Handlers"
        B1["Action Handlers (src/ActionHandler)"]:::action
    end
    A3 -->|"routesCommand"| B1
    A4 -->|"routesQuery"| B1

    %% Domain Layer
    subgraph "Domain Layer"
        C1["Domain Entities (src/Entity)"]:::domain
        C2["Domain Services (src/Service)"]:::domain
        C3["Repositories (src/EntityRepository)"]:::domain
        C4["DTOs (src/EntityDTO)"]:::domain
        C5["DTO Builders (src/EntityDTO/Builder)"]:::domain
        C6["Domain Events (src/Event)"]:::domain
        C7["Event Dispatcher (src/Lib/Event)"]:::domain
    end
    B1 -->|"processesCommand"| C1
    B1 -->|"invokesService"| C2
    C2 -->|"persistsVia"| C3
    C1 -->|"buildsDTO"| C5
    C5 -->|"producesDTO"| C4
    C1 -->|"raisesEvent"| C6
    C6 -->|"dispatchedBy"| C7

    %% Infrastructure/Lib Layer
    subgraph "Infrastructure Layer"
        D1["Lib Utilities (src/Lib)"]:::infra
        D2["Payment Gateway (src/Lib/PaymentGateway)"]:::infra
        D3["Shipment Gateway (src/Lib/ShipmentGateway)"]:::infra
        D4["File Manager (src/Lib/LocalFileManager)"]:::infra
        D5["Mapper (src/Lib/Mapper)"]:::infra
        D6["Uuid (src/Lib/Uuid)"]:::infra
        D7["Uuid Binary (src/Doctrine/Extensions/UuidBinaryType)"]:::infra
        D8["XML Serializer (src/Lib/XMLSerializer)"]:::infra
    end
    C2 -->|"utilizes"| D1
    C2 -->|"integratesWith"| D2
    C2 -->|"integratesWith"| D3
    C2 -->|"utilizes"| D4
    C2 -->|"utilizes"| D5
    D1 -->|"providesUuid"| D6
    D6 -->|"extendedBy"| D7
    D1 -->|"providesXML"| D8

    %% Configuration & Doctrine Mapping
    subgraph "Configuration & Mapping"
        E1["Configuration (config)"]:::config
        E2["Doctrine Mapping (src/Doctrine/Mapping)"]:::config
    end
    C3 -->|"configuredBy"| E1
    C3 -->|"usesMapping"| E2

    %% Click Events for Application Layer
    click A2 "https://github.com/inklabs/kommerce-core/tree/master/src/Action"
    click A3 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib/Command"
    click A4 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib/Query"

    %% Click Event for Action Handlers
    click B1 "https://github.com/inklabs/kommerce-core/tree/master/src/ActionHandler"

    %% Click Events for Domain Layer
    click C1 "https://github.com/inklabs/kommerce-core/tree/master/src/Entity"
    click C2 "https://github.com/inklabs/kommerce-core/tree/master/src/Service"
    click C3 "https://github.com/inklabs/kommerce-core/tree/master/src/EntityRepository"
    click C4 "https://github.com/inklabs/kommerce-core/tree/master/src/EntityDTO"
    click C5 "https://github.com/inklabs/kommerce-core/tree/master/src/EntityDTO/Builder"
    click C6 "https://github.com/inklabs/kommerce-core/tree/master/src/Event"
    click C7 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib/Event"

    %% Click Events for Infrastructure Layer
    click D1 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib"
    click D2 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib/PaymentGateway"
    click D3 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib/ShipmentGateway"
    click D4 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib/LocalFileManager"
    click D5 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib/Mapper"
    click D6 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib/Uuid"
    click D7 "https://github.com/inklabs/kommerce-core/tree/master/src/Doctrine/Extensions/UuidBinaryType"
    click D8 "https://github.com/inklabs/kommerce-core/tree/master/src/Lib/XMLSerializer"

    %% Click Events for Configuration & Mapping
    click E1 "https://github.com/inklabs/kommerce-core/tree/master/config"
    click E2 "https://github.com/inklabs/kommerce-core/tree/master/src/Doctrine/Mapping"

    %% Style Classes
    classDef app fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef action fill:#d1e0e0,stroke:#333,stroke-width:2px;
    classDef domain fill:#cceeff,stroke:#333,stroke-width:2px;
    classDef infra fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef config fill:#ffcccb,stroke:#333,stroke-width:2px;
```
