# System Map — magento-orderwebhook

> **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-orderwebhook` sends Magento 2 order data to the NGauge platform as a JSON webhook whenever a customer places an order or an order transitions to `processing` status. The module:

1. Listens to two Magento order events (`sales_order_place_after` and `sales_order_save_after`).
2. Builds a JSON payload containing full order details (customer, addresses, items, payment summary, shipping).
3. Posts the payload to a configurable NGauge endpoint with Bearer token authentication, with automatic retry on failure.
4. Stores the NGauge-assigned order reference (`ngauge_order_no`, `ngauge_order_id`, `ngauge_order_link`) back on the Magento order.
5. Provides an admin UI panel on the order view page showing NGauge sync status, with a button to send unsynchronised orders.
6. Provides a CLI command for connectivity testing.

---

## L0 Context Diagram

```mermaid
%% Title: magento-orderwebhook — 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, config keys

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
  ngauge[NGauge Platform]:::external

  subgraph Magento[Magento 2 Platform]
    webhook_module[OrderWebhook Module]:::system
    sales_module[Sales Module]:::system
    sales_order_db[(sales_order DB)]:::data
    config_store[(Config Store)]:::data
  end

  store_customer -->|"Places order"| sales_module
  sales_module -->|"order events"| webhook_module
  admin_user -->|"Resend / Test webhook"| webhook_module
  webhook_module -->|"POST JSON webhook"| ngauge
  ngauge -->|"Order no / ID / link"| webhook_module
  webhook_module -->|"Write ngauge fields"| sales_order_db
  webhook_module -->|"Read API key / config"| config_store
```

---

## Actors and Systems

| Actor / System | Role | Notes |
|----------------|------|-------|
| Store Customer | Triggers order placement via checkout | Frontend orders fire `order_placed` webhook |
| Admin User | Views sync status on order; manually resends webhook; runs CLI test | Admin-created orders wait for `processing` status change |
| Sales Module (`Magento_Sales`) | Event source; shared `sales_order` table | Module declares dependency in `module.xml` |
| NGauge Platform | Webhook recipient and source of truth for NGauge order references | Default: `https://ahshub.portalpeople.app` |
| Config Store (`core_config_data`) | Stores encrypted API key and all module config | API key decrypted at send time |
| sales_order DB | Stores 3 NGauge-specific columns added by this module | `ngauge_order_no`, `ngauge_order_id`, `ngauge_order_link` |

---

## Key Characteristics

| Property | Value |
|----------|-------|
| Activation | Magento event observers — fires on `sales_order_place_after` and `sales_order_save_after` |
| Authentication to NGauge | Bearer token (API key, encrypted at rest) |
| Retry | Exponential backoff, configurable attempts (default: 3) |
| Order blocking | None — webhook failure is logged but does not block order processing |
| Re-entrancy guard | Static flag prevents recursive observer loops on `orderRepository->save()` |
| Admin-created orders | Skipped on `sales_order_place_after`; handled on `sales_order_save_after` when status → `processing` |
| comment_only mode | Configurable — NGauge response stored as comment only, `ngauge_*` fields not written |
| Git | Own repository — `portalpeople/magento-orderwebhook` |

---

## Full Documentation Index

| Document | Purpose |
|----------|---------|
| [README.md](../README.md) | Module overview (note: version history inaccurate — see AUDIT.md F3) |
| [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) | Webhook payload schema, event types, admin routes, CLI command |
| [BOUNDARIES.md](BOUNDARIES.md) | Internal components, external dependencies, gap classifications |
| [DATA_OWNERSHIP.md](DATA_OWNERSHIP.md) | DB columns added, PII/special-category 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, failure handling |
| [SECURITY.md](SECURITY.md) | Security findings, transport controls, PII summary |
| [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 |
