> ## 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 multi-channel, multi-agent architecture for dispute operations

This system is built around a workflow backbone. Deployments bring work into Duckie, workflows hold deterministic state, and agents handle judgment-heavy steps.

## Operational Flow

```mermaid theme={null}
flowchart TD
  Event["Payment processor event or ticket update"]
  Event --> Intake["Intake deployment"]
  Intake --> Validate["Case validation workflow"]
  Validate --> Main["Dispute handling workflow"]

  Main --> Classify["Reason classification agent"]
  Classify --> Route{"Next action"}

  Route -->|Accept or close| Close["Close or record decision"]
  Route -->|Need account context| Account["Account communication agent"]
  Route -->|Prepare response| Evidence["Evidence preparation workflow"]

  Account --> Wait["Wait for account response"]
  Wait --> Evidence

  Evidence --> Draft["Evidence drafting agent"]
  Draft --> Approval["Human approval workflow"]
  Approval --> Escalation["Slack escalation agent"]
  Escalation --> Reviewers["Operations reviewers"]
  Reviewers --> Decision{"Reviewer decision"}

  Decision -->|Approved| Submit["Submission or recording workflow"]
  Decision -->|Changes requested| Evidence
  Decision -->|Manual handling| Manual["Manual review queue"]

  Submit --> Outcome["Outcome tracking workflow"]
  Close --> Runs["Runs and analytics"]
  Manual --> Runs
  Outcome --> Runs
```

## Reporting and Improvement Loop

```mermaid theme={null}
flowchart TD
  Runs["Runs and analytics"]
  Runs --> Scheduler["Scheduler deployment"]
  Scheduler --> Reporting["Duckie Assistant reporting agent"]
  Reporting --> Stakeholders["Stakeholder Slack channel"]

  Runs --> Feedback["Duckie Assistant feedback agent"]
  Stakeholders --> Feedback
  Feedback --> Proposals["Improvement proposals"]
  Proposals --> Review["System owner review"]
  Review --> Updates["Guidelines, workflows, tools, and categories"]
  Updates --> Testing["Replay and batch testing"]
  Testing --> Deploy["Updated deployments"]
```

## Component Responsibilities

| Component | Responsibility |
| - | - |
| **Intake deployment** | Starts the system from a ticket, webhook, or processor event. |
| **Dispute handling workflow** | Owns case state, deterministic branches, retries, and handoffs. |
| **Case validation workflow** | Normalizes the case record and checks required fields. |
| **Reason classification agent** | Interprets messy dispute text and chooses the most likely reason. |
| **Decision policy workflow** | Applies deterministic accept, counter, close, and escalation rules. |
| **Account communication agent** | Contacts the account or merchant for missing information. |
| **Evidence preparation workflow** | Calls tools and agents to assemble the draft evidence packet. |
| **Human approval workflow** | Requires a reviewer decision before final submission. |
| **Slack escalation agent** | Sends structured questions and returns structured answers through the internal review channel. |
| **Duckie Assistant reporting agent** | Reads runs and posts a scheduled digest for stakeholders. |
| **Duckie Assistant feedback agent** | Reviews runs and corrections to recommend improvements to Duckie configuration. |

## Deterministic vs Autonomous

Use deterministic workflows for:

* Required field checks
* Deadline calculation
* Branch routing
* Approval gates
* Submission status changes
* Retrying failed tool calls
* Calling reusable subflows

Use autonomous agents for:

* Classifying unclear reason codes
* Reading free-form dispute notes
* Drafting account messages
* Drafting evidence narratives
* Summarizing reviewer feedback
* Explaining daily operational trends
* Delegating narrow tasks to other agents

> [!TIP]
>
> When a step must happen the same way every time, make it a workflow. When a step needs interpretation, make it an agent called by the workflow.

## Deployment Inventory

| Deployment | Trigger | Target | Mode to start |
| - | - | - | - |
| **Dispute intake** | Ticketing event, custom webhook, or processor webhook | Dispute handling workflow | Testing |
| **Slack escalation** | Internal Slack channel or responder behavior from workflow | Escalation agent | Testing |
| **Daily stakeholder report** | Scheduler, such as weekdays at 9 AM | Duckie Assistant reporting agent | Testing |
| **Feedback review** | Scheduler or manual internal request | Duckie Assistant feedback agent | Testing |

## Related Docs

> [card] [Deployments](https://docs.duckie.ai/deployments/overview.md)
>
> Learn how deployments connect triggers to agents and workflows.

> [card] [Custom Webhooks](https://docs.duckie.ai/deployments/custom-webhooks.md)
>
> Trigger Duckie from external systems.

> [card] [Scheduled Deployments](https://docs.duckie.ai/deployments/scheduled-deployments.md)
>
> Run reporting and review loops on a schedule.

> [card] [Runs](https://docs.duckie.ai/analytics/runs.md)
>
> Inspect what happened during each case.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.