> ## 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.
</Tip>

## 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

<CardGroup cols={2}>
  <Card title="Deployments" icon="rocket" href="/deployments/overview">
    Learn how deployments connect triggers to agents and workflows.
  </Card>

  <Card title="Custom Webhooks" icon="plug" href="/deployments/custom-webhooks">
    Trigger Duckie from external systems.
  </Card>

  <Card title="Scheduled Deployments" icon="clock" href="/deployments/scheduled-deployments">
    Run reporting and review loops on a schedule.
  </Card>

  <Card title="Runs" icon="clock-rotate-left" href="/analytics/runs">
    Inspect what happened during each case.
  </Card>
</CardGroup>