# aws-samples/sample-multi-agent-procure-to-pay architecture

> Architecture diagram of the GitHub repository aws-samples/sample-multi-agent-procure-to-pay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-multi-agent-procure-to-pay
- Repository: https://github.com/aws-samples/sample-multi-agent-procure-to-pay

## Overview

ARIA is an agentic procure-to-pay platform: a user request is handled by specialized agents, approved or escalated, then carried through sourcing, purchase order, receiving, invoice matching and payment against ERPNext. The browser SPA presents operational workflows; FastAPI serves operational endpoints, while a canonical adapter mediates ERP data access and lifecycle services track runs and decisions. The README documents AgentCore, Cedar authorization, a formal-reasoning guardrail and optional simulation; unsampled implementation details are represented conservatively, and links without direct evidence are omitted.

Main entry points: [`backend/agentcore_app.py`](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agentcore_app.py) (AgentCore runtime), [`backend/api/invoices.py`](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/api/invoices.py) (Invoice processing), [`frontend/src/App.tsx`](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/frontend/src/App.tsx) (ARIA SPA), [`backend/adapters/canonical_api.py`](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/adapters/canonical_api.py) (Canonical ERP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_spa["ARIA SPA<br/>[App.tsx]"]
  node_requisition_ui["Requisition workflow<br/>[Requisitions.tsx]"]
  node_invoice_ui["Invoice workflow<br/>[Invoices.tsx]"]
  node_agent_stream["Agent stream hook<br/>[useAgentStream.ts]"]
end

subgraph group_operations["API and lifecycle"]
  node_api["Operational API<br/>[main.py]"]
  node_chat_api["Chat endpoints<br/>[chat.py]"]
  node_invoice_api["Invoice processing<br/>[invoices.py]"]
  node_identity["User identity<br/>[auth.py]"]
  node_lifecycle["Lifecycle tracking<br/>[lifecycle.py]"]
  node_lifecycle_store[("Lifecycle store<br/>[dynamo.py]")]
  node_textract["Invoice extraction<br/>[textract.py]"]
end

subgraph group_agents["Procurement agents"]
  node_agent_runtime["AgentCore runtime<br/>[agentcore_app.py]"]
  node_chat_agent["Chat agent<br/>[chat_agent.py]"]
  node_requisition_agent["Requisition agent"]
  node_sourcing_agent["Sourcing agent<br/>[sourcing_agent.py]"]
  node_workflow_agent["P2P workflow agent<br/>[p2p_workflow.py]"]
  node_po_agent["PO management agent"]
  node_receiving_agent["Receiving agent<br/>[receiving_agent.py]"]
  node_matching_agent["Invoice matching"]
  node_payment_agent["Payment agent<br/>[payment_agent.py]"]
  node_mcp_gateway["AgentCore Gateway"]
end

subgraph group_erp["ERP integration"]
  node_canonical_api["Canonical ERP API<br/>[canonical_api.py]"]
  node_erp_client["ERP transport client<br/>[erp_client.py]"]
  node_adapter_base["Adapter contract"]
  node_erpnext_adapter["ERPNext adapter<br/>[adapter.py]"]
  node_erpnext_client["ERPNext REST client<br/>[client.py]"]
end

subgraph group_simulation["Demo simulation"]
  node_simulation["Scenario simulator<br/>[simulator.py]"]
  node_simulation_api["Simulation API client<br/>[api_client.py]"]
  node_simulation_state[("Scenario state<br/>[state_manager.py]")]
end

node_user(("Procurement user"))
node_erpnext[("ERPNext")]
node_bedrock["Amazon Bedrock"]
node_human_approver(("Human approver"))

node_user -->|"uses"| node_spa
node_spa -->|"routes to"| node_requisition_ui
node_spa -->|"routes to"| node_invoice_ui
node_requisition_ui -->|"invokes"| node_agent_stream
node_agent_stream -->|"streams invocation"| node_agent_runtime
node_spa -.->|"uses operations"| node_api
node_api -->|"registers routes"| node_chat_api
node_api -->|"registers routes"| node_invoice_api
node_chat_api -.->|"authenticates user"| node_identity
node_invoice_api -->|"gets user email"| node_identity
node_invoice_api -->|"extracts invoice"| node_textract
node_invoice_api -->|"creates invoice"| node_erp_client
node_invoice_api -.->|"tracks progress"| node_lifecycle
node_lifecycle -->|"reads and writes"| node_lifecycle_store
node_agent_runtime -->|"loads"| node_requisition_agent
node_agent_runtime -->|"loads"| node_sourcing_agent
node_agent_runtime -->|"loads"| node_workflow_agent
node_agent_runtime -->|"loads"| node_po_agent
node_agent_runtime -->|"loads"| node_receiving_agent
node_agent_runtime -->|"loads"| node_matching_agent
node_agent_runtime -->|"loads"| node_payment_agent
node_chat_agent -->|"calls"| node_erp_client
node_agent_runtime -->|"connects tools"| node_mcp_gateway
node_mcp_gateway -.->|"routes ERP tools"| node_canonical_api
node_canonical_api -->|"implements contract"| node_adapter_base
node_canonical_api -->|"dispatches"| node_erpnext_adapter
node_erpnext_adapter -->|"calls"| node_erpnext_client
node_erpnext_client -->|"reads and writes"| node_erpnext
node_erp_client -->|"invokes adapter"| node_canonical_api
node_human_approver -.->|"reviews decisions"| node_spa
node_simulation -->|"calls API"| node_simulation_api
node_simulation -.->|"tracks scenarios"| node_simulation_state
node_simulation -.->|"generates narratives"| node_bedrock

click node_spa "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/frontend/src/App.tsx"
click node_requisition_ui "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/frontend/src/pages/Requisitions.tsx"
click node_invoice_ui "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/frontend/src/pages/Invoices.tsx"
click node_agent_stream "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/frontend/src/hooks/useAgentStream.ts"
click node_api "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/main.py"
click node_chat_api "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/api/chat.py"
click node_invoice_api "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/api/invoices.py"
click node_identity "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/auth.py"
click node_lifecycle "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/lifecycle.py"
click node_lifecycle_store "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/dynamo.py"
click node_agent_runtime "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agentcore_app.py"
click node_chat_agent "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/chat_agent.py"
click node_requisition_agent "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/requisition_agent.py"
click node_sourcing_agent "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/sourcing_agent.py"
click node_workflow_agent "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/p2p_workflow.py"
click node_po_agent "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/po_management_agent.py"
click node_receiving_agent "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/receiving_agent.py"
click node_matching_agent "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/invoice_matching_agent.py"
click node_payment_agent "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/payment_agent.py"
click node_canonical_api "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/adapters/canonical_api.py"
click node_erp_client "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/erp_client.py"
click node_adapter_base "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/adapters/erp_adapter_base.py"
click node_erpnext_adapter "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/adapters/erpnext/adapter.py"
click node_erpnext_client "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/adapters/erpnext/client.py"
click node_textract "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/textract.py"
click node_simulation "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/utilities/simulation/simulator.py"
click node_simulation_api "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/utilities/simulation/api_client.py"
click node_simulation_state "https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/utilities/simulation/state_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa,node_requisition_ui,node_invoice_ui,node_agent_stream,node_user toneBlue
class node_api,node_chat_api,node_invoice_api,node_identity,node_lifecycle,node_lifecycle_store,node_textract,node_erpnext toneAmber
class node_agent_runtime,node_chat_agent,node_requisition_agent,node_sourcing_agent,node_workflow_agent,node_po_agent,node_receiving_agent,node_matching_agent,node_payment_agent,node_mcp_gateway toneMint
class node_canonical_api,node_erp_client,node_adapter_base,node_erpnext_adapter,node_erpnext_client toneRose
class node_simulation,node_simulation_api,node_simulation_state,node_bedrock,node_human_approver toneIndigo
```

## Components

### User experience

- [ARIA SPA](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Requisition workflow](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/frontend/src/pages/Requisitions.tsx): `frontend/src/pages/Requisitions.tsx`
- [Invoice workflow](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/frontend/src/pages/Invoices.tsx): `frontend/src/pages/Invoices.tsx`
- [Agent stream hook](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/frontend/src/hooks/useAgentStream.ts): `frontend/src/hooks/useAgentStream.ts`

### API and lifecycle

- [Operational API](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/main.py): `backend/main.py`
- [Chat endpoints](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/api/chat.py): `backend/api/chat.py`
- [Invoice processing](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/api/invoices.py): `backend/api/invoices.py`
- [User identity](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/auth.py): `backend/services/auth.py`
- [Lifecycle tracking](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/lifecycle.py): `backend/services/lifecycle.py`
- [Lifecycle store](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/dynamo.py): `backend/services/dynamo.py`
- [Invoice extraction](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/textract.py): `backend/services/textract.py`

### Procurement agents

- [AgentCore runtime](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agentcore_app.py): `backend/agentcore_app.py`
- [Chat agent](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/chat_agent.py): `backend/agents/chat_agent.py`
- [Requisition agent](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/requisition_agent.py): `backend/agents/requisition_agent.py`
- [Sourcing agent](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/sourcing_agent.py): `backend/agents/sourcing_agent.py`
- [P2P workflow agent](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/p2p_workflow.py): `backend/agents/p2p_workflow.py`
- [PO management agent](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/po_management_agent.py): `backend/agents/po_management_agent.py`
- [Receiving agent](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/receiving_agent.py): `backend/agents/receiving_agent.py`
- [Invoice matching](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/invoice_matching_agent.py): `backend/agents/invoice_matching_agent.py`
- [Payment agent](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/agents/payment_agent.py): `backend/agents/payment_agent.py`
- **AgentCore Gateway**

### ERP integration

- [Canonical ERP API](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/adapters/canonical_api.py): `backend/adapters/canonical_api.py`
- [ERP transport client](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/services/erp_client.py): `backend/services/erp_client.py`
- [Adapter contract](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/adapters/erp_adapter_base.py): `backend/adapters/erp_adapter_base.py`
- [ERPNext adapter](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/adapters/erpnext/adapter.py): `backend/adapters/erpnext/adapter.py`
- [ERPNext REST client](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/backend/adapters/erpnext/client.py): `backend/adapters/erpnext/client.py`

### Demo simulation

- [Scenario simulator](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/utilities/simulation/simulator.py): `utilities/simulation/simulator.py`
- [Simulation API client](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/utilities/simulation/api_client.py): `utilities/simulation/api_client.py`
- [Scenario state](https://github.com/aws-samples/sample-multi-agent-procure-to-pay/blob/main/utilities/simulation/state_manager.py): `utilities/simulation/state_manager.py`

### Other components

- **Procurement user**
- **ERPNext**
- **Amazon Bedrock**
- **Human approver**

## Connections

- Procurement user → ARIA SPA: uses
- ARIA SPA → Requisition workflow: routes to (evidence: `frontend/src/App.tsx`)
- ARIA SPA → Invoice workflow: routes to (evidence: `frontend/src/App.tsx`)
- Requisition workflow → Agent stream hook: invokes (evidence: `frontend/src/pages/Requisitions.tsx`)
- Agent stream hook → AgentCore runtime: streams invocation (evidence: `frontend/src/hooks/useAgentStream.ts`)
- ARIA SPA → Operational API: uses operations
- Operational API → Chat endpoints: registers routes (evidence: `backend/main.py`)
- Operational API → Invoice processing: registers routes (evidence: `backend/main.py`)
- Chat endpoints → User identity: authenticates user
- Invoice processing → User identity: gets user email (evidence: `backend/api/invoices.py`)
- Invoice processing → Invoice extraction: extracts invoice (evidence: `backend/api/invoices.py`)
- Invoice processing → ERP transport client: creates invoice (evidence: `backend/api/invoices.py`)
- Invoice processing → Lifecycle tracking: tracks progress (evidence: `backend/api/invoices.py`)
- Lifecycle tracking → Lifecycle store: reads and writes (evidence: `backend/services/lifecycle.py`)
- AgentCore runtime → Requisition agent: loads (evidence: `backend/agentcore_app.py`)
- AgentCore runtime → Sourcing agent: loads (evidence: `backend/agentcore_app.py`)
- AgentCore runtime → P2P workflow agent: loads (evidence: `backend/agentcore_app.py`)
- AgentCore runtime → PO management agent: loads (evidence: `backend/agentcore_app.py`)
- AgentCore runtime → Receiving agent: loads (evidence: `backend/agentcore_app.py`)
- AgentCore runtime → Invoice matching: loads (evidence: `backend/agentcore_app.py`)
- AgentCore runtime → Payment agent: loads (evidence: `backend/agentcore_app.py`)
- Chat agent → ERP transport client: calls (evidence: `backend/agents/chat_agent.py`)
- AgentCore runtime → AgentCore Gateway: connects tools (evidence: `backend/agentcore_app.py`)
- AgentCore Gateway → Canonical ERP API: routes ERP tools
- Canonical ERP API → Adapter contract: implements contract (evidence: `backend/adapters/canonical_api.py`)
- Canonical ERP API → ERPNext adapter: dispatches (evidence: `backend/adapters/canonical_api.py`)
- ERPNext adapter → ERPNext REST client: calls (evidence: `backend/adapters/erpnext/adapter.py`)
- ERPNext REST client → ERPNext: reads and writes (evidence: `backend/adapters/erpnext/client.py`)
- ERP transport client → Canonical ERP API: invokes adapter (evidence: `backend/services/erp_client.py`)
- Human approver → ARIA SPA: reviews decisions
- Scenario simulator → Simulation API client: calls API (evidence: `utilities/simulation/api_client.py`)
- Scenario simulator → Scenario state: tracks scenarios
- Scenario simulator → Amazon Bedrock: generates narratives
