# System Map — magento-shippingfields

> **Layer:** L0 Context
> **Last verified:** 2026-02-26 (Europe/London)
> **Owner:** Engineering
> **Audience:** New developers, non-technical stakeholders
>
> For internal components, see [architecture.md](architecture.md).
> For integration detail, see [INTEGRATIONS.md](INTEGRATIONS.md).

---

## What This Module Does

`magento-shippingfields` adds two custom fields to the Magento 2 checkout shipping step:

- **Shipping Date** — a date picker for the customer's preferred delivery date, with configurable disabled weekdays and specific blocked dates
- **Shipping Message** — a free-text field for special delivery instructions (max 255 chars)

The module:

1. Displays the fields in the checkout shipping step (frontend Knockout.js UI).
2. Saves the field values to the customer's quote via a REST API call.
3. Transfers the values from quote to order when the order is placed.
4. Shows and allows editing of the fields on the Magento admin order view.
5. Provides disabled-date configuration to the frontend from the `portalpeople/magento-disableddates` module.

---

## 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 plugins, extension attributes, 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 fields"| quote_db
  sales_module -->|"Order submit event"| shipping_module
  shipping_module -->|"Copy fields to order"| order_db
  admin_user -->|"View / Edit order fields"| shipping_module
  disabled_dates -->|"Disabled dates"| shipping_module
```

---

## Actors and Systems

| Actor / System | Role | Notes |
|----------------|------|-------|
| Store Customer | Enters shipping date and message at checkout | Fields optional (layout); validation in JS mixin |
| Admin User | Views and edits shipping fields on order | Admin route `shippingfields/order/update` |
| Checkout Module (`Magento_Checkout`) | Plugin target for shipping step interception | `ShippingInformationManagementPlugin` intercepts here |
| Quote Module (`Magento_Quote`) | Data store (quote); plugin target | Fields saved to `quote.shipping_date`, `shipping_message` |
| Sales Module (`Magento_Sales`) | Data store (order); event source | Fields transferred to `sales_order` on order submit |
| DisabledDates Module (`portalpeople/magento-disableddates`) | Source of disabled dates/weekdays for date picker | Not declared in `composer.json` |

---

## Key Characteristics

| Property | Value |
|----------|-------|
| Checkout fields | `shipping_date` (date picker), `shipping_message` (textarea, max 255 chars) |
| Data stores | `quote` + `sales_order` — 2 columns each |
| REST API | `POST /V1/carts/mine/save-shipping-fields` (anonymous) |
| Extension attributes | On `CartInterface` and `OrderInterface` |
| Admin UI | Order view + order edit with save controller |
| Disabled-date config | From `portalpeople/magento-disableddates` + `portalpeople_disableddates` Magento config |
| Known issue | Synchronous AJAX in `place-order-mixin.js` |
| Version | v1.0.18 (`composer.json`) / `setup_version="1.0.0"` (`module.xml`) — mismatch |
| Tests | None |

---

## Full Documentation Index

| Document | Purpose |
|----------|---------|
| [README.md](../README.md) | Module overview, install instructions |
| [AI_GUIDELINES.md](../AI_GUIDELINES.md) | AI assistant operating rules for this module |
| [architecture.md](architecture.md) | L0/L1/L3 architecture diagrams |
| [API.md](API.md) | REST endpoint, extension attributes, plugin contracts, admin routes |
| [BOUNDARIES.md](BOUNDARIES.md) | Internal components, external dependencies, gap classifications |
| [DATA_OWNERSHIP.md](DATA_OWNERSHIP.md) | DB columns, PII assessment, data retention |
| [GDPR.md](GDPR.md) | Organisational data protection policy |
| [INTEGRATIONS.md](INTEGRATIONS.md) | Full integration catalogue with evidence |
| [OBSERVABILITY.md](OBSERVABILITY.md) | Logging coverage, PII in logs |
| [SECURITY.md](SECURITY.md) | Security findings, access controls |
| [WORKFLOW.md](WORKFLOW.md) | Local dev setup, known issues, PR checklist |
| [AUDIT.md](AUDIT.md) | Full audit findings with severity and recommendations |
| [TODO.md](TODO.md) | Prioritised backlog of code and documentation work |
| [adr/ADR-000-discovery-baseline.md](adr/ADR-000-discovery-baseline.md) | Discovery baseline — all confirmed facts and unknowns |
