# rakhargo/cova architecture

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

- Interactive diagram: https://gitdiagram.com/rakhargo/cova
- Repository: https://github.com/rakhargo/cova

## Overview

Cova is stablecoin authorization-and-capture infrastructure: customers deposit USDG, authorize a maximum, and merchants capture the final amount or release the remainder. The primary user workflow runs through the Next.js playground and wallet controller into the CovaVault contract; the contract holds customer funds and settles captures directly to merchants. The repo also includes a reusable SDK for contract reads, writes, signed authorizations, and event history. Edges reflect excerpts or README statements; implementation details not sampled are left at the documented subsystem level.

Main entry points: [`lib/use-cova.ts`](https://github.com/rakhargo/cova/blob/main/lib/use-cova.ts) (Cova Controller), [`contracts/src/CovaVault.sol`](https://github.com/rakhargo/cova/blob/main/contracts/src/CovaVault.sol) (CovaVault), [`components/cova-playground.tsx`](https://github.com/rakhargo/cova/blob/main/components/cova-playground.tsx) (Payment Playground), [`sdk/src/client.ts`](https://github.com/rakhargo/cova/blob/main/sdk/src/client.ts) (SDK Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_playground["Playground"]
  node_page["App Entry<br/>[page.tsx]"]
  node_playground_ui["Payment Playground"]
  node_hold_card["Hold Actions<br/>[hold-card.tsx]"]
  node_signed_ui["Signed Authorization UI"]
end

subgraph group_integration["Wallet Integration"]
  node_controller["Cova Controller<br/>[use-cova.ts]"]
  node_deployment["Deployment and State Reads<br/>[chain.ts]"]
  node_validation["Input Validation<br/>[validation.ts]"]
  node_transactions["Receipt Confirmation<br/>[transactions.ts]"]
  node_demo["Demo State<br/>[demo.ts]"]
end

subgraph group_protocol["Onchain Protocol"]
  node_usdg{{"USDG Token"}}
  node_vault["CovaVault<br/>[CovaVault.sol]"]
end

subgraph group_sdk["Reusable SDK"]
  node_sdk_client["SDK Client<br/>[client.ts]"]
  node_authorization["Authorization Encoding<br/>[authorization.ts]"]
  node_sdk_history["Event History Reader<br/>[history.ts]"]
  node_sdk_abi["Vault ABI<br/>[abi.ts]"]
end

subgraph group_history["History and Metadata"]
  node_metadata[("Local Hold Metadata<br/>[history.ts]")]
end

node_customer(("Customer"))
node_merchant(("Merchant"))
node_anyone(("Expiry Caller"))
node_wallet{{"Wallet"}}
node_network{{"Arbitrum Network"}}

node_customer -->|"uses"| node_playground_ui
node_merchant -->|"uses"| node_playground_ui
node_anyone -->|"releases expired"| node_vault
node_page -->|"renders"| node_playground_ui
node_playground_ui -->|"reads and acts"| node_controller
node_playground_ui -.->|"renders"| node_hold_card
node_playground_ui -->|"renders"| node_signed_ui
node_hold_card -.->|"invokes actions"| node_controller
node_signed_ui -->|"invokes signing"| node_controller
node_controller -->|"validates inputs"| node_validation
node_controller -->|"verifies and reads"| node_deployment
node_controller -->|"confirms receipts"| node_transactions
node_controller -->|"merges history"| node_metadata
node_controller -->|"simulates demo"| node_demo
node_controller -.->|"requests signatures"| node_wallet
node_deployment -->|"reads state"| node_vault
node_deployment -->|"checks version"| node_sdk_client
node_vault -->|"transfers funds"| node_usdg
node_wallet -->|"submits transactions"| node_vault
node_vault -->|"runs on"| node_network
node_sdk_client -->|"reads and writes"| node_vault
node_sdk_client -->|"validates signatures"| node_authorization
node_sdk_client -->|"reads event history"| node_sdk_history
node_sdk_client -->|"uses bindings"| node_sdk_abi
node_controller -->|"scans events"| node_sdk_history
node_merchant -->|"captures or releases"| node_vault
node_customer -->|"deposits and authorizes"| node_vault
node_vault -->|"withdraws or releases"| node_customer

click node_page "https://github.com/rakhargo/cova/blob/main/app/page.tsx"
click node_playground_ui "https://github.com/rakhargo/cova/blob/main/components/cova-playground.tsx"
click node_hold_card "https://github.com/rakhargo/cova/blob/main/components/hold-card.tsx"
click node_signed_ui "https://github.com/rakhargo/cova/blob/main/components/signed-authorizations.tsx"
click node_controller "https://github.com/rakhargo/cova/blob/main/lib/use-cova.ts"
click node_deployment "https://github.com/rakhargo/cova/blob/main/lib/chain.ts"
click node_validation "https://github.com/rakhargo/cova/blob/main/lib/validation.ts"
click node_transactions "https://github.com/rakhargo/cova/blob/main/lib/transactions.ts"
click node_metadata "https://github.com/rakhargo/cova/blob/main/lib/history.ts"
click node_vault "https://github.com/rakhargo/cova/blob/main/contracts/src/CovaVault.sol"
click node_sdk_client "https://github.com/rakhargo/cova/blob/main/sdk/src/client.ts"
click node_authorization "https://github.com/rakhargo/cova/blob/main/sdk/src/authorization.ts"
click node_sdk_history "https://github.com/rakhargo/cova/blob/main/sdk/src/history.ts"
click node_sdk_abi "https://github.com/rakhargo/cova/blob/main/sdk/src/abi.ts"
click node_demo "https://github.com/rakhargo/cova/blob/main/lib/demo.ts"

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_page,node_playground_ui,node_hold_card,node_signed_ui toneBlue
class node_controller,node_deployment,node_validation,node_transactions,node_demo toneAmber
class node_usdg,node_vault toneMint
class node_sdk_client,node_authorization,node_sdk_history,node_sdk_abi toneRose
class node_metadata,node_customer,node_merchant,node_anyone,node_wallet,node_network toneIndigo
```

## Components

### Playground

- [App Entry](https://github.com/rakhargo/cova/blob/main/app/page.tsx): `app/page.tsx`
- [Payment Playground](https://github.com/rakhargo/cova/blob/main/components/cova-playground.tsx): `components/cova-playground.tsx`
- [Hold Actions](https://github.com/rakhargo/cova/blob/main/components/hold-card.tsx): `components/hold-card.tsx`
- [Signed Authorization UI](https://github.com/rakhargo/cova/blob/main/components/signed-authorizations.tsx): `components/signed-authorizations.tsx`

### Wallet Integration

- [Cova Controller](https://github.com/rakhargo/cova/blob/main/lib/use-cova.ts): `lib/use-cova.ts`
- [Deployment and State Reads](https://github.com/rakhargo/cova/blob/main/lib/chain.ts): `lib/chain.ts`
- [Input Validation](https://github.com/rakhargo/cova/blob/main/lib/validation.ts): `lib/validation.ts`
- [Receipt Confirmation](https://github.com/rakhargo/cova/blob/main/lib/transactions.ts): `lib/transactions.ts`
- [Demo State](https://github.com/rakhargo/cova/blob/main/lib/demo.ts): `lib/demo.ts`

### Onchain Protocol

- **USDG Token**
- [CovaVault](https://github.com/rakhargo/cova/blob/main/contracts/src/CovaVault.sol): `contracts/src/CovaVault.sol`

### Reusable SDK

- [SDK Client](https://github.com/rakhargo/cova/blob/main/sdk/src/client.ts): `sdk/src/client.ts`
- [Authorization Encoding](https://github.com/rakhargo/cova/blob/main/sdk/src/authorization.ts): `sdk/src/authorization.ts`
- [Event History Reader](https://github.com/rakhargo/cova/blob/main/sdk/src/history.ts): `sdk/src/history.ts`
- [Vault ABI](https://github.com/rakhargo/cova/blob/main/sdk/src/abi.ts): `sdk/src/abi.ts`

### History and Metadata

- [Local Hold Metadata](https://github.com/rakhargo/cova/blob/main/lib/history.ts): `lib/history.ts`

### Other components

- **Customer**
- **Merchant**
- **Expiry Caller**
- **Wallet**
- **Arbitrum Network**

## Connections

- Customer → Payment Playground: uses (evidence: `README.md`)
- Merchant → Payment Playground: uses (evidence: `README.md`)
- Expiry Caller → CovaVault: releases expired (evidence: `README.md`)
- App Entry → Payment Playground: renders (evidence: `app/page.tsx`)
- Payment Playground → Cova Controller: reads and acts (evidence: `components/cova-playground.tsx`)
- Payment Playground → Hold Actions: renders (evidence: `components/cova-playground.tsx`)
- Payment Playground → Signed Authorization UI: renders (evidence: `components/cova-playground.tsx`)
- Hold Actions → Cova Controller: invokes actions
- Signed Authorization UI → Cova Controller: invokes signing (evidence: `components/signed-authorizations.tsx`)
- Cova Controller → Input Validation: validates inputs (evidence: `lib/use-cova.ts`)
- Cova Controller → Deployment and State Reads: verifies and reads (evidence: `lib/use-cova.ts`)
- Cova Controller → Receipt Confirmation: confirms receipts (evidence: `lib/use-cova.ts`)
- Cova Controller → Local Hold Metadata: merges history (evidence: `lib/use-cova.ts`)
- Cova Controller → Demo State: simulates demo (evidence: `lib/use-cova.ts`)
- Cova Controller → Wallet: requests signatures
- Deployment and State Reads → CovaVault: reads state (evidence: `lib/chain.ts`)
- Deployment and State Reads → SDK Client: checks version (evidence: `lib/chain.ts`)
- CovaVault → USDG Token: transfers funds (evidence: `README.md`)
- Wallet → CovaVault: submits transactions (evidence: `README.md`)
- CovaVault → Arbitrum Network: runs on (evidence: `README.md`)
- SDK Client → CovaVault: reads and writes (evidence: `sdk/src/client.ts`)
- SDK Client → Authorization Encoding: validates signatures (evidence: `sdk/src/client.ts`)
- SDK Client → Event History Reader: reads event history (evidence: `sdk/src/client.ts`)
- SDK Client → Vault ABI: uses bindings (evidence: `sdk/src/client.ts`)
- Cova Controller → Event History Reader: scans events (evidence: `lib/use-cova.ts`)
- Merchant → CovaVault: captures or releases (evidence: `README.md`)
- Customer → CovaVault: deposits and authorizes (evidence: `README.md`)
- CovaVault → Customer: withdraws or releases (evidence: `README.md`)
