# dheerajgowdads/paari_payments_protocol architecture

> Architecture diagram of the GitHub repository dheerajgowdads/paari_payments_protocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dheerajgowdads/paari_payments_protocol
- Repository: https://github.com/dheerajgowdads/paari_payments_protocol

## Overview

Paari is a governed payment service for AI agents: an agent presents a parent-authorized identity, authenticates, proposes a payment, and receives a bounded authorization only after policy checks. The payment boundary executes it through a provider; verified provider events and direct reconciliation establish settlement, with audit and proof records supporting accountability. The README documents major protocol, mandate, autonomous-provider, tenant, and settlement capabilities. Some subsystem links are based on that documentation and the tree; unsampled implementation details are not assumed.

Main entry points: [`app/routers/payments.py`](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/payments.py) (Payment Orchestration), [`app/main.py`](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/main.py) (Paari API), [`app/database.py`](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/database.py) (Persistent State), [`app/providers/base.py`](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/providers/base.py) (Provider Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trust["Identity & Trust"]
  node_agents["Agent Registration<br/>[agents.py]"]
  node_parents["Parent Governance<br/>[parents.py]"]
  node_trustlogic["Trust Validation<br/>[trust.py]"]
  node_mandates["User Mandates<br/>[mandates.py]"]
end

subgraph group_protocol["Protocol &amp; Access"]
  node_sdk["Agent Client SDK<br/>[client.py]"]
  node_api["Paari API<br/>[main.py]"]
  node_discovery["Protocol Discovery<br/>[discovery.py]"]
  node_envelope["Signed Envelopes<br/>[envelope.py]"]
  node_auth["Proof Authentication<br/>[auth.py]"]
end

subgraph group_governance["Payment Governance"]
  node_payments["Payment Orchestration<br/>[payments.py]"]
  node_policy["Governance Rules<br/>[governance.py]"]
  node_mandatesigning["Mandate Signing<br/>[mandate_signing.py]"]
  node_state["Transaction State<br/>[transitions.py]"]
end

subgraph group_settlement["Provider Settlement"]
  node_provider["Provider Interface<br/>[base.py]"]
  node_razorpay["Razorpay Adapter<br/>[razorpay.py]"]
  node_agentic["Autonomous Adapter"]
  node_reference["Reference Provider"]
  node_webhook["Settlement Webhooks<br/>[payments.py]"]
  node_reconcile["Provider Reconciliation<br/>[reconcile.py]"]
  node_worker["Reconciliation Worker"]
end

subgraph group_accountability["Audit &amp; Evidence"]
  node_audit["Hash-chain Audit<br/>[audit.py]"]
  node_proof["Proof Bundle<br/>[proof_bundle.py]"]
  node_database[("Persistent State<br/>[database.py]")]
end

node_agent(("AI Agent"))
node_parent(("Parent Authority"))
node_provider_service(("Payment Provider"))

node_agent -->|"uses"| node_sdk
node_sdk -->|"sends requests"| node_api
node_api -->|"serves discovery"| node_discovery
node_sdk -->|"signs messages"| node_envelope
node_api -->|"routes registration"| node_agents
node_api -->|"routes authority"| node_parents
node_parents -->|"delegates authority"| node_agents
node_agents -->|"validates trust"| node_trustlogic
node_agents -->|"stores identity"| node_database
node_api -->|"routes authentication"| node_auth
node_auth -->|"checks credentials"| node_database
node_agent -->|"proves possession"| node_auth
node_api -->|"routes payment requests"| node_payments
node_agent -->|"proposes payment"| node_payments
node_payments -->|"revalidates trust"| node_trustlogic
node_payments -->|"resolves mandate"| node_mandates
node_payments -->|"evaluates intent"| node_policy
node_payments -->|"verifies mandate"| node_mandatesigning
node_payments -->|"reserves authorization"| node_database
node_payments -->|"applies transitions"| node_state
node_payments -->|"executes authorization"| node_provider
node_provider -->|"implemented by"| node_razorpay
node_provider -.->|"autonomous option"| node_agentic
node_provider -.->|"conformance option"| node_reference
node_razorpay -->|"calls provider API"| node_provider_service
node_agentic -.->|"calls provider API"| node_provider_service
node_reference -.->|"returns provider result"| node_payments
node_provider_service -->|"sends events"| node_webhook
node_webhook -->|"records legal transition"| node_state
node_webhook -->|"records event"| node_database
node_api -->|"starts worker"| node_worker
node_worker -->|"reconciles transactions"| node_reconcile
node_reconcile -->|"reads provider truth"| node_provider
node_reconcile -->|"confirms settlement"| node_state
node_worker -->|"loads pending transactions"| node_database
node_payments -->|"records events"| node_audit
node_auth -->|"records authentication"| node_audit
node_reconcile -->|"records reconciliation"| node_audit
node_audit -->|"appends entries"| node_database
node_api -->|"serves proof bundle"| node_proof
node_proof -->|"reads stage evidence"| node_database

click node_sdk "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/sdk/paari_agent/client.py"
click node_api "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/main.py"
click node_discovery "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/protocol/discovery.py"
click node_envelope "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/protocol/envelope.py"
click node_auth "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/auth.py"
click node_agents "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/agents.py"
click node_parents "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/parents.py"
click node_trustlogic "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/trust.py"
click node_mandates "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/mandates.py"
click node_payments "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/payments.py"
click node_policy "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/governance.py"
click node_mandatesigning "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/mandate_signing.py"
click node_state "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/transitions.py"
click node_provider "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/providers/base.py"
click node_razorpay "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/providers/razorpay.py"
click node_agentic "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/providers/razorpay_agentic.py"
click node_reference "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/providers/reference_autonomous.py"
click node_webhook "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/payments.py"
click node_reconcile "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/reconcile.py"
click node_worker "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/reconcile_worker.py"
click node_audit "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/audit.py"
click node_proof "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/proof_bundle.py"
click node_database "https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/database.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_agents,node_parents,node_trustlogic,node_mandates toneBlue
class node_sdk,node_api,node_discovery,node_envelope,node_auth toneAmber
class node_payments,node_policy,node_mandatesigning,node_state toneMint
class node_provider,node_razorpay,node_agentic,node_reference,node_webhook,node_reconcile,node_worker toneRose
class node_audit,node_proof,node_database,node_agent,node_parent,node_provider_service toneIndigo
```

## Components

### Identity & Trust

- [Agent Registration](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/agents.py): `app/routers/agents.py`
- [Parent Governance](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/parents.py): `app/routers/parents.py`
- [Trust Validation](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/trust.py): `app/trust.py`
- [User Mandates](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/mandates.py): `app/mandates.py`

### Protocol & Access

- [Agent Client SDK](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/sdk/paari_agent/client.py): `sdk/paari_agent/client.py`
- [Paari API](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/main.py): `app/main.py`
- [Protocol Discovery](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/protocol/discovery.py): `app/protocol/discovery.py`
- [Signed Envelopes](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/protocol/envelope.py): `app/protocol/envelope.py`
- [Proof Authentication](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/auth.py): `app/routers/auth.py`

### Payment Governance

- [Payment Orchestration](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/payments.py): `app/routers/payments.py`
- [Governance Rules](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/governance.py): `app/governance.py`
- [Mandate Signing](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/mandate_signing.py): `app/mandate_signing.py`
- [Transaction State](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/transitions.py): `app/transitions.py`

### Provider Settlement

- [Provider Interface](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/providers/base.py): `app/providers/base.py`
- [Razorpay Adapter](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/providers/razorpay.py): `app/providers/razorpay.py`
- [Autonomous Adapter](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/providers/razorpay_agentic.py): `app/providers/razorpay_agentic.py`
- [Reference Provider](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/providers/reference_autonomous.py): `app/providers/reference_autonomous.py`
- [Settlement Webhooks](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/routers/payments.py): `app/routers/payments.py`
- [Provider Reconciliation](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/reconcile.py): `app/reconcile.py`
- [Reconciliation Worker](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/reconcile_worker.py): `app/reconcile_worker.py`

### Audit & Evidence

- [Hash-chain Audit](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/audit.py): `app/audit.py`
- [Proof Bundle](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/proof_bundle.py): `app/proof_bundle.py`
- [Persistent State](https://github.com/dheerajgowdads/paari_payments_protocol/blob/main/app/database.py): `app/database.py`

### Other components

- **AI Agent**
- **Parent Authority**
- **Payment Provider**

## Connections

- AI Agent → Agent Client SDK: uses
- Agent Client SDK → Paari API: sends requests
- Paari API → Protocol Discovery: serves discovery
- Agent Client SDK → Signed Envelopes: signs messages
- Paari API → Agent Registration: routes registration
- Paari API → Parent Governance: routes authority
- Parent Governance → Agent Registration: delegates authority
- Agent Registration → Trust Validation: validates trust
- Agent Registration → Persistent State: stores identity
- Paari API → Proof Authentication: routes authentication
- Proof Authentication → Persistent State: checks credentials
- AI Agent → Proof Authentication: proves possession
- Paari API → Payment Orchestration: routes payment requests
- AI Agent → Payment Orchestration: proposes payment
- Payment Orchestration → Trust Validation: revalidates trust
- Payment Orchestration → User Mandates: resolves mandate
- Payment Orchestration → Governance Rules: evaluates intent
- Payment Orchestration → Mandate Signing: verifies mandate
- Payment Orchestration → Persistent State: reserves authorization
- Payment Orchestration → Transaction State: applies transitions
- Payment Orchestration → Provider Interface: executes authorization
- Provider Interface → Razorpay Adapter: implemented by
- Provider Interface → Autonomous Adapter: autonomous option
- Provider Interface → Reference Provider: conformance option
- Razorpay Adapter → Payment Provider: calls provider API
- Autonomous Adapter → Payment Provider: calls provider API
- Reference Provider → Payment Orchestration: returns provider result
- Payment Provider → Settlement Webhooks: sends events
- Settlement Webhooks → Transaction State: records legal transition
- Settlement Webhooks → Persistent State: records event
- Paari API → Reconciliation Worker: starts worker
- Reconciliation Worker → Provider Reconciliation: reconciles transactions
- Provider Reconciliation → Provider Interface: reads provider truth
- Provider Reconciliation → Transaction State: confirms settlement
- Reconciliation Worker → Persistent State: loads pending transactions
- Payment Orchestration → Hash-chain Audit: records events
- Proof Authentication → Hash-chain Audit: records authentication
- Provider Reconciliation → Hash-chain Audit: records reconciliation
- Hash-chain Audit → Persistent State: appends entries
- Paari API → Proof Bundle: serves proof bundle
- Proof Bundle → Persistent State: reads stage evidence