# Architecture — magento-shippingfields

> **Last verified:** 2026-02-26 (Europe/London)
> **Owner:** Engineering
> **Mermaid standard:** `/modules/magento-shippingfields/docs/MERMAID_DIAGRAM_STANDARDS.md`

---

## Confirmed Facts

1. Module ID: `PortalPeople_ShippingFields` — registered in `/modules/magento-shippingfields/src/etc/module.xml`.
2. Package: `portalpeople/magento-shippingfields` v1.0.18 (`composer.json`) vs `setup_version="1.0.0"` in `module.xml` — version conflict.
3. Module declares sequence dependencies on `Magento_Checkout`, `Magento_Quote`, `Magento_Sales`.
4. Two custom fields added to checkout and order: `shipping_date` (date) and `shipping_message` (text, 255 chars max).
5. Fields stored in two tables: `quote` and `sales_order` — both use columns `shipping_date` (DATE, nullable) and `shipping_message` (varchar/text, nullable).
6. Extension attributes declared for `Magento\Quote\Api\Data\CartInterface` and `Magento\Sales\Api\Data\OrderInterface` in `extension_attributes.xml`.
7. REST API endpoint `POST /V1/carts/mine/save-shipping-fields` saves fields to the active quote (anonymous auth).
8. `ShippingInformationManagementPlugin` is the primary capture point on the backend: extracts `shipping_date` and `shipping_message` from the request JSON during shipping information save.
9. `QuoteSubmitBefore` observer (`sales_model_service_quote_submit_before`) copies fields from quote to order during order submission.
10. Six plugins registered: `QuoteRepositoryPlugin`, `CartRepositoryPlugin`, `OrderRepositoryPlugin`, `QuoteToOrderPlugin`, `PaymentInformationManagementPlugin`, `ShippingInformationManagementPlugin`.
11. `DeliveryDateConfigProvider` provides disabled weekdays, disabled dates (from `portalpeople/magento-disableddates` collection), and a lead-time window (today + next 2 working days) to the frontend via `window.checkoutConfig.portalpeopleShippingFields`.
12. Frontend uses three RequireJS mixins to intercept checkout flow: `set-shipping-information-mixin.js` (shipping step completion), `place-order-mixin.js` (order placement), `date-disabled-weekdays-mixin.js` (date picker configuration).
13. `place-order-mixin.js` uses synchronous AJAX (`async: false`) to save fields during order placement — blocks the browser main thread.
14. Admin interface: `ShippingFields` block (view) and `Edit/ShippingFields` block (edit) with `Update` controller for POST saves.
15. Backup files exist in source: `sales_order_edit_index.xml.bak` and `place-order-mixin.js.bak` — not active.
16. Stray file `Untitled-1.html` exists in `src/view/adminhtml/` — not part of the module.
17. `PaymentInformationManagementPlugin` performs debug logging only — no field capture in this plugin.
18. Logging is PSR-3, verbose with emoji-prefixed messages throughout all major operations.
19. No PHPUnit tests or test configuration found.
20. External dependency: `portalpeople/magento-disableddates` — used by `DeliveryDateConfigProvider` for disabled date collection. **Not declared in `composer.json` require block.**

---

## L0 Context Diagram

```mermaid
%% Title: magento-shippingfields — L0 System Context
%% Layer: L0
%% Owner: Engineering
%% Last verified: 2026-02-26 (Europe/London)
%% Scope: External actors and systems that touch the module
%% Excludes: Internal components, DB columns, JS mixins

flowchart LR
classDef external stroke-width:1.5px;
classDef system stroke-width:1.5px;
classDef data stroke-dasharray:3 3,stroke-width:1.5px;

  store_customer[Store Customer]:::external
  admin_user[Admin User]:::external

  subgraph Magento[Magento 2 Platform]
    shipping_module[ShippingFields Module]:::system
    checkout_module[Checkout Module]:::system
    sales_module[Sales Module]:::system
    disabled_dates[DisabledDates Module]:::system
    quote_db[(quote DB)]:::data
    order_db[(sales_order DB)]:::data
  end

  store_customer -->|"Checkout shipping step"| checkout_module
  checkout_module -->|"Set shipping information"| shipping_module
  store_customer -->|"Place order"| shipping_module
  shipping_module -->|"Save shipping_date / message"| quote_db
  sales_module -->|"sales_model_service_quote_submit_before"| shipping_module
  shipping_module -->|"Copy fields quote → order"| order_db
  admin_user -->|"View / Edit order fields"| shipping_module
  disabled_dates -->|"Disabled dates collection"| shipping_module
```

---

## L1 Containers Diagram

```mermaid
%% Title: magento-shippingfields — L1 Containers
%% Layer: L1
%% Owner: Engineering
%% Last verified: 2026-02-26 (Europe/London)
%% Scope: Major components inside the module and adjacent Magento services
%% Excludes: Internal class methods

flowchart LR
classDef external stroke-width:1.5px;
classDef system stroke-width:1.5px;
classDef data stroke-dasharray:3 3,stroke-width:1.5px;

  subgraph Frontend[Frontend Checkout]
    fe_shipping_step[Shipping Step UI]:::system
    fe_mixins[JS Mixins]:::system
    fe_config[CheckoutConfig Provider]:::system
  end

  subgraph Backend[Magento Backend]
    rest_api[REST API Endpoint]:::system
    plugins[Plugins Layer]:::system
    observer[QuoteSubmitBefore Observer]:::system
    admin_ui[Admin Order UI]:::system
    config_provider[DeliveryDateConfigProvider]:::system
  end

  subgraph Data[Data Layer]
    quote_db[(quote)]:::data
    order_db[(sales_order)]:::data
    disabled_dates_db[(DisabledDates DB)]:::data
  end

  fe_shipping_step --> fe_mixins
  fe_mixins -->|"POST /V1/carts/mine/save-shipping-fields"| rest_api
  fe_config -->|"window.checkoutConfig"| fe_shipping_step
  config_provider --> fe_config
  config_provider -->|"read disabled dates"| disabled_dates_db
  rest_api -->|"save to quote"| quote_db
  plugins -->|"sync extension attrs"| quote_db
  plugins -->|"sync extension attrs"| order_db
  observer -->|"copy quote → order"| order_db
  admin_ui -->|"view/edit fields"| order_db
```

---

## L3 Flow: Frontend Checkout — Shipping Fields Capture

```mermaid
sequenceDiagram
  %% Title: magento-shippingfields — Checkout Shipping Fields Capture (L3)
  %% Layer: L3
  %% Owner: Engineering
  %% Last verified: 2026-02-26 (Europe/London)
  %% Scope: Customer completes shipping step through to fields saved on quote
  %% Excludes: Date picker disabled-day logic, payment step

  autonumber
  actor Customer
  participant UI as Checkout UI
  participant Mixin as set-shipping-information-mixin
  participant API as REST API
  participant Plugin as ShippingInformationManagementPlugin
  participant Quote as quote DB

  Customer->>UI: Enter shipping date and message
  Customer->>UI: Click "Next" (proceed to payment)
  UI->>Mixin: beforeSaveAddressInformation (intercepted)
  Mixin->>Mixin: Read fields from checkoutProvider
  Mixin->>API: POST /V1/carts/mine/save-shipping-fields
  API->>Quote: Save shipping_date + shipping_message
  Quote-->>API: OK
  API-->>Mixin: true
  Mixin->>Plugin: saveAddressInformation continues
  Plugin->>Plugin: Extract fields from request JSON
  Plugin->>Quote: Set fields on quote (redundant path)
```

---

## L3 Flow: Quote to Order Transfer

```mermaid
sequenceDiagram
  %% Title: magento-shippingfields — Quote to Order Transfer (L3)
  %% Layer: L3
  %% Owner: Engineering
  %% Last verified: 2026-02-26 (Europe/London)
  %% Scope: Order placed — shipping fields copied from quote to sales_order
  %% Excludes: Payment processing, inventory checks

  autonumber
  participant Magento as Magento Sales
  participant Observer as QuoteSubmitBefore
  participant Order as sales_order DB

  Magento->>Observer: sales_model_service_quote_submit_before
  Observer->>Observer: Read shipping_date from quote
  Observer->>Observer: Read shipping_message from quote
  Observer->>Order: Set shipping_date on order object
  Observer->>Order: Set shipping_message on order object
  Magento->>Order: Persist order (Magento core save)
```

---

## Unknowns

1. `UNKNOWN — Requires Clarification`: Is `portalpeople/magento-disableddates` guaranteed to be installed in all environments? No `require` entry in `composer.json`.
2. `UNKNOWN — Requires Clarification`: What happens if `DeliveryDateConfigProvider` cannot find the `DisabledDates` collection? Does it fail silently or throw?
3. `UNKNOWN — Requires Clarification`: Does `set-shipping-information-mixin.js` block checkout progression if the REST API call fails?
4. `UNKNOWN — Requires Clarification`: Is the `shipping_date` field required on the frontend? The layout XML marks it optional but the mixin appears to validate it.
5. `UNKNOWN — Requires Clarification`: What is the canonical version of this module? `composer.json` v1.0.18 vs `module.xml` `setup_version="1.0.0"`.

---

## Evidence

- `/modules/magento-shippingfields/src/etc/module.xml`
- `/modules/magento-shippingfields/src/etc/events.xml`
- `/modules/magento-shippingfields/src/etc/di.xml`
- `/modules/magento-shippingfields/src/etc/frontend/di.xml`
- `/modules/magento-shippingfields/src/etc/extension_attributes.xml`
- `/modules/magento-shippingfields/src/etc/webapi.xml`
- `/modules/magento-shippingfields/src/etc/adminhtml/routes.xml`
- `/modules/magento-shippingfields/src/Api/ShippingFieldsInterface.php`
- `/modules/magento-shippingfields/src/Model/ShippingFieldsManagement.php`
- `/modules/magento-shippingfields/src/Model/Checkout/DeliveryDateConfigProvider.php`
- `/modules/magento-shippingfields/src/Observer/QuoteSubmitBefore.php`
- `/modules/magento-shippingfields/src/Plugin/ShippingInformationManagementPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/QuoteRepositoryPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/CartRepositoryPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/OrderRepositoryPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/QuoteToOrderPlugin.php`
- `/modules/magento-shippingfields/src/Plugin/PaymentInformationManagementPlugin.php`
- `/modules/magento-shippingfields/src/Block/Adminhtml/Order/ShippingFields.php`
- `/modules/magento-shippingfields/src/Block/Adminhtml/Order/Edit/ShippingFields.php`
- `/modules/magento-shippingfields/src/Controller/Adminhtml/Order/Update.php`
- `/modules/magento-shippingfields/src/view/frontend/web/js/action/set-shipping-information-mixin.js`
- `/modules/magento-shippingfields/src/view/frontend/web/js/action/place-order-mixin.js`
- `/modules/magento-shippingfields/src/view/frontend/web/js/form/element/date-disabled-weekdays-mixin.js`
- `/modules/magento-shippingfields/src/view/frontend/layout/checkout_index_index.xml`
- `/modules/magento-shippingfields/composer.json`
