> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jaantonio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How ingress works

> Follow a CargoWise outbound delivery through capture, XML interpretation, routing, and acknowledgment.

CargoWise chooses a module lane by sending XML to that module's configured outbound target. Lambda
then authenticates the delivery, records the source evidence, and performs the safe handoff for that
lane.

## The flow

```mermaid theme={null}
flowchart LR
  A["CargoWise outbound target"] --> B["Lambda ingress authentication"]
  B --> C["Capture event and payload"]
  C --> D{"Configured module lane"}
  D -->|"Stamping"| E["Parse, classify, and map accounting XML"]
  E --> F["Store document and queue durable work"]
  F --> G["Acknowledge delivery"]
  D -->|"Analytics"| H["Store and schedule payload"]
  H --> I["Acknowledge delivery"]
  H --> J["Parse and project asynchronously"]
```

1. **CargoWise outbound** sends the XML to the target configured for Stamping or Analytics.
2. **Lambda ingress** checks authentication, organization access, module entitlement, and payload
   size.
3. Lambda records the event and source payload so the delivery can be inspected later.
4. The selected lane performs its own validation and durable handoff.
5. Lambda acknowledges the delivery. Later module work continues independently.

## How XML becomes data

An XML parser first converts XML syntax into a structure that application code can safely inspect.
For example:

```xml theme={null}
<DataSource>
  <Type>AccountingInvoice</Type>
  <Key>AR INV IPME2603000019</Key>
</DataSource>
```

becomes a structure similar to:

```ts theme={null}
{
  DataSource: {
    Type: "AccountingInvoice",
    Key: "AR INV IPME2603000019",
  },
}
```

Nested elements become nested values. Repeated elements become a collection. The parser handles XML
syntax; it does not know the business meaning of `AccountingInvoice`, `PostingJournalCollection`, or
`GovernmentNumber`.

Lambda applies explicit CargoWise mappings after parsing:

| Stage                     | Responsibility                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------ |
| **XML parsing**           | Validate XML syntax and convert elements, attributes, and repeated nodes             |
| **CargoWise recognition** | Identify the organization, envelope, message type, and primary business transaction  |
| **Module mapping**        | Interpret supported fields for Stamping or project source observations for Analytics |

This split is intentional. Hand-writing an XML parser would duplicate difficult rules around
namespaces, attributes, escaping, and repeated elements. A generic parser alone would still not know
which CargoWise fields represent a customer, invoice line, payment parent, or reporting entity.

## The Stamping lane

The Stamping path recognizes supported accounting messages, including income invoices, payment
receipts, credits, and receipt cancellations. It maps the selected transaction into Lambda's
normalized Stamping data before durable work is queued.

If the XML is malformed, ambiguous, unsupported for the route, or belongs to a disabled module,
Lambda does not guess through it. The delivery is rejected with a response that can be inspected in
the Ingress workspace.

## The Analytics lane

Analytics uses its own CargoWise outbound target. Ingress captures and acknowledges the delivery,
then an asynchronous projector parses the complete source and records observations before building
recognized reporting entities.

Because projection happens after acceptance, an Analytics delivery can be **Accepted** before its
values are queryable. Invalid XML appears later as a projection problem instead of an ingress
rejection. A readable but unsupported object family remains available as source observations without
typed business entities.

Read [How Analytics works](/analytics/how-it-works) for the source observation and reporting layers.

<Accordion title="Implementation note: parser and SDK">
  The Stamping path uses `fast-xml-parser` inside `@jaantonio/cargowise-sdk`. The SDK validates the
  XML, preserves attributes, removes namespace prefixes, trims values, disables entity processing,
  and enforces payload and nesting limits. `@jaantonio/cw-adaptor` then applies the accounting
  mappings used by Stamping.

  Analytics also uses a standard XML parser, but its projector produces a complete node and
  observation model instead of a Stamping transaction object. The two paths share the principle of
  standard parsing plus explicit business interpretation; they do not share one output model.
</Accordion>

## Before module work starts

A delivery cannot continue safely when:

* authentication or organization identity does not match
* the payload is empty or exceeds the route limit
* the required module is not enabled
* the Stamping XML is invalid, unknown, or does not match the selected route

Open [Ingress workspace](/ingress/workspace) to find the event outcome, response, parsed messages,
and product relationship.