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

# System Map

> The workflow backbone, specialist agents, and proactive loops for WISMO operations

This system is built around a deterministic workflow backbone. Deployments bring WISMO work into Duckie, workflows hold case state and approval gates, and autonomous agents handle investigation, interpretation, customer communication, and internal review.

## Operational Flow

```mermaid theme={null}
flowchart TD
  Sources["Ticket, chat, email, OMS, WMS, supplier, carrier, or scheduler event"]
  Sources --> Deployments["Deployments and filters"]
  Deployments --> Intake["WISMO intake workflow or triage agent"]
  Intake --> Orchestrator["WISMO orchestration workflow"]
  Orchestrator --> Context["Order context workflow"]
  Context --> Investigate["Order investigation agent"]
  Investigate --> Router["Condition routing workflow"]

  Router --> Standard["Standard status agent"]
  Router --> Supplier["Supplier backorder agent"]
  Router --> Warehouse["Warehouse investigation agent"]
  Router --> Split["Split shipment agent"]
  Router --> Carrier["Carrier exception agent"]
  Router --> DNR["Delivered-not-received agent"]
  Router --> Hold["Guarded hold workflow"]

  Standard --> Comms["Customer communications agent"]
  Supplier --> Comms
  Warehouse --> Comms
  Split --> Comms
  Carrier --> Comms
  DNR --> Resolution["Resolution eligibility workflow"]
  Hold --> Comms

  Resolution --> Approval["Human approval workflow"]
  Approval --> Slack["Slack escalation agent"]
  Slack --> Reviewers["CX, shipping, supply-chain, or fraud reviewer"]
  Reviewers --> Decision{"Reviewer decision"}

  Decision -->|Approved| Execute["Execute approved action or create final draft"]
  Decision -->|Needs change| Orchestrator
  Decision -->|Manual takeover| Manual["Manual handling queue"]

  Comms --> Followup["Proactive follow-up monitor"]
  Execute --> Comms
  Followup --> Orchestrator
  Manual --> Runs["Runs and analytics"]
  Comms --> Runs
```

## Proactive Event Loop

```mermaid theme={null}
sequenceDiagram
  participant Backend as OMS, WMS, supplier, or carrier
  participant Deployment as Duckie event deployment
  participant Monitor as Proactive follow-up monitor
  participant Case as WISMO case state
  participant Specialist as Specialist agent
  participant Comms as Customer communications agent
  participant Channel as Ticketing or messaging channel

  Backend->>Deployment: status_changed(order_id, shipment_id, event_type)
  Deployment->>Monitor: start proactive run
  Monitor->>Case: load last customer update and saved follow-up
  Monitor->>Monitor: dedupe and decide whether action is needed
  Monitor->>Specialist: interpret ambiguous status change if needed
  Specialist-->>Monitor: recommended action and customer-safe facts
  Monitor->>Comms: draft proactive update
  Comms->>Channel: update active case or send outbound message
  Comms->>Case: save last_status_sent and next_follow_up_due_at
```

## Component Responsibilities

| Component                           | Responsibility                                                                                                                    |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Customer WISMO deployment**       | Starts from a support ticket, chat, email reply, or customer message.                                                             |
| **Backend event deployments**       | Start from OMS, WMS, supplier, inventory, carrier, or scheduled exception events.                                                 |
| **WISMO orchestration workflow**    | Owns case state, deterministic branches, approvals, retries, follow-up timing, and closure.                                       |
| **Order context workflow**          | Pulls canonical order, shipment, fulfillment, inventory, supplier, carrier, hold, and support-history fields.                     |
| **Order investigation agent**       | Resolves missing or conflicting facts before routing.                                                                             |
| **Condition routing workflow**      | Applies auditable condition labels and routes to the right specialist or controlled workflow.                                     |
| **Specialist agents**               | Handle standard status, supplier backorder, warehouse delay, split shipment, carrier exception, and delivered-not-received paths. |
| **Customer communications agent**   | Sends replies and proactive updates with approved tone, current facts, next action, and follow-up timing.                         |
| **Resolution eligibility workflow** | Applies deterministic eligibility and approval rules before replacement, refund, cancellation, or address-change actions.         |
| **Slack escalation agent**          | Asks targeted internal questions, collects reviewer decisions, and writes structured answers back to the case.                    |
| **Proactive follow-up monitor**     | Deduplicates backend events, compares them to prior customer updates, and triggers the right next action.                         |

## Deterministic vs Autonomous

Use deterministic workflows for:

* Customer/order identity checks
* Canonical data gathering
* Condition routing when backend statuses are clear
* Saved values and follow-up commitments
* Duplicate suppression
* Approval gates
* High-impact writes
* Closure and classification

Use autonomous agents for:

* Interpreting conflicting order data
* Choosing which read-only tools to call next
* Explaining supplier, warehouse, and carrier exceptions
* Drafting customer-safe language
* Summarizing prior support history
* Asking internal teams focused questions
* Turning reviewer replies into structured case updates

<Tip>
  When a WISMO step must happen the same way every time, make it a workflow. When it needs interpretation, make it an agent called by the workflow.
</Tip>

## Deployment Inventory

| Deployment                       | Trigger                                                                            | Target                                | Mode to start |
| -------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------- | ------------- |
| **Customer WISMO intake**        | Ticket tag, chat intent, email rule, or support group                              | WISMO intake workflow or triage agent | Testing       |
| **OMS order event**              | Order status, hold status, cancellation, payment, or fulfillment change            | OMS event workflow                    | Testing       |
| **WMS fulfillment event**        | Pick delay, short pick, label creation, pack completion, or handoff event          | Warehouse event workflow or agent     | Testing       |
| **Supplier and inventory event** | Supplier ETA, allocation, stockout, or inbound receiving change                    | Supplier backorder agent              | Testing       |
| **Carrier tracking event**       | First scan, no movement, delivery attempt, RTS, delivered, or investigation update | Carrier event workflow or agent       | Testing       |
| **Scheduled exception sweep**    | Hourly or business-hours schedule                                                  | Proactive follow-up monitor           | Testing       |
| **Slack escalation**             | Internal review thread reply or app mention                                        | Slack escalation agent                | Testing       |

## Related Docs

<CardGroup cols={2}>
  <Card title="Routing and Orchestration" icon="route" href="/concepts/routing-and-orchestration-patterns">
    Choose the right mix of deployments, workflows, agents, and human review.
  </Card>

  <Card title="Custom Webhooks" icon="plug" href="/deployments/custom-webhooks">
    Trigger Duckie from OMS, WMS, supplier, inventory, and carrier systems.
  </Card>

  <Card title="Scheduled Deployments" icon="clock" href="/deployments/scheduled-deployments">
    Run exception sweeps and follow-up monitors.
  </Card>

  <Card title="Runs" icon="clock-rotate-left" href="/analytics/runs">
    Inspect each WISMO run and tool call.
  </Card>
</CardGroup>