# milesdevx/pactora architecture

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

- Interactive diagram: https://gitdiagram.com/milesdevx/pactora
- Repository: https://github.com/milesdevx/pactora

## Overview

Pactora is a web-and-Telegram app for milestone-based MUSD escrow on Mezo Testnet. Clients create wallet-owned agreements, providers accept, clients fund them, providers submit evidence, and clients approve releases; the product also supports timeout claims, guarded refunds, mutual settlement, public receipts, verified metadata, and wallet-linked Telegram commands and alerts. The graph follows the documented lifecycle and sampled module references. Some implementation details, including contract source and notification delivery, were not sampled, so those links are omitted or marked unverified.

Main entry points: [`app/agreements/[id]/page.tsx`](https://github.com/milesdevx/pactora/blob/main/app/agreements/%5Bid%5D/page.tsx) (Agreement actions), [`lib/db/schema.ts`](https://github.com/milesdevx/pactora/blob/main/lib/db/schema.ts) (PostgreSQL records), [`app/api/agreements/route.ts`](https://github.com/milesdevx/pactora/blob/main/app/api/agreements/route.ts) (Agreement API), [`lib/telegram/webhook.ts`](https://github.com/milesdevx/pactora/blob/main/lib/telegram/webhook.ts) (Bot command handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_home["Product landing<br/>[page.tsx]"]
  node_dashboard["Agreement dashboard<br/>[page.tsx]"]
end

subgraph group_escrow["Escrow lifecycle"]
  node_create["Create agreement<br/>[page.tsx]"]
  node_detail["Agreement actions<br/>[page.tsx]"]
  node_txhook["Confirmed transactions"]
  node_terms["Terms and amounts<br/>[terms.ts]"]
end

subgraph group_identity["Identity and records"]
  node_agreementsapi["Agreement API<br/>[route.ts]"]
  node_evidenceapi["Evidence API<br/>[route.ts]"]
  node_agreementapi["Agreement detail API<br/>[route.ts]"]
  node_auth["Wallet authentication<br/>[session.ts]"]
  node_authroutes["Session routes<br/>[route.ts]"]
  node_metadata["Agreement metadata<br/>[metadata.ts]"]
  node_db[("PostgreSQL records<br/>[schema.ts]")]
end

subgraph group_telegram["Telegram integration"]
  node_telegramsettings["Telegram settings<br/>[page.tsx]"]
  node_telegramlink["Telegram linking API<br/>[route.ts]"]
  node_webhookroute["Telegram webhook route<br/>[route.ts]"]
  node_bot["Bot command handling<br/>[webhook.ts]"]
  node_chainreads["Wallet chain reads<br/>[chain-reads.ts]"]
  node_notifications["Alert delivery<br/>[notifications.ts]"]
end

subgraph group_chain["Mezo services"]
  node_receipts["Public receipts<br/>[receipts.ts]"]
  node_receiptsapi["Receipt endpoint<br/>[route.ts]"]
  node_chainserver["Chain verification<br/>[server.ts]"]
end

node_parties(("Client and provider"))
node_mezo{{"Mezo Testnet"}}
node_telegram{{"Telegram"}}

node_parties -->|"visit"| node_home
node_home -->|"start agreement"| node_create
node_parties -->|"set terms"| node_create
node_create -->|"submit transaction"| node_txhook
node_txhook -->|"hash terms"| node_terms
node_create -->|"create on-chain"| node_mezo
node_parties -->|"accept and fund"| node_detail
node_detail -->|"execute actions"| node_txhook
node_parties -->|"register evidence"| node_evidenceapi
node_parties -->|"submit and approve"| node_detail
node_detail -->|"release or settle"| node_mezo
node_parties -->|"claim timeout or refund"| node_detail
node_dashboard -.->|"show agreements"| node_parties
node_agreementsapi -->|"require session"| node_auth
node_agreementsapi -->|"verify chain state"| node_chainserver
node_agreementsapi -->|"list verified"| node_metadata
node_agreementsapi -->|"store metadata"| node_db
node_evidenceapi -->|"read and write"| node_db
node_agreementapi -->|"read party agreement"| node_chainserver
node_agreementapi -->|"verify metadata"| node_db
node_authroutes -.->|"manage session"| node_auth
node_chainserver -->|"read contract"| node_mezo
node_receiptsapi -->|"read confirmed receipt"| node_chainserver
node_receiptsapi -->|"format receipt"| node_receipts
node_telegramsettings -->|"manage link"| node_telegramlink
node_telegramlink -->|"require session"| node_auth
node_telegramlink -->|"persist link token"| node_db
node_telegram -->|"send updates"| node_webhookroute
node_webhookroute -->|"dispatch updates"| node_bot
node_bot -->|"read and update links"| node_db
node_bot -->|"read balances"| node_chainreads
node_bot -->|"manage alerts"| node_notifications
node_notifications -.->|"deliver alerts"| node_telegram

click node_home "https://github.com/milesdevx/pactora/blob/main/app/page.tsx"
click node_dashboard "https://github.com/milesdevx/pactora/blob/main/app/dashboard/page.tsx"
click node_create "https://github.com/milesdevx/pactora/blob/main/app/agreements/create/page.tsx"
click node_detail "https://github.com/milesdevx/pactora/blob/main/app/agreements/%5Bid%5D/page.tsx"
click node_txhook "https://github.com/milesdevx/pactora/blob/main/lib/hooks/useConfirmedTransaction.ts"
click node_terms "https://github.com/milesdevx/pactora/blob/main/lib/chain/terms.ts"
click node_agreementsapi "https://github.com/milesdevx/pactora/blob/main/app/api/agreements/route.ts"
click node_evidenceapi "https://github.com/milesdevx/pactora/blob/main/app/api/agreements/%5Bid%5D/evidence/route.ts"
click node_agreementapi "https://github.com/milesdevx/pactora/blob/main/app/api/agreements/%5Bid%5D/route.ts"
click node_auth "https://github.com/milesdevx/pactora/blob/main/lib/security/session.ts"
click node_authroutes "https://github.com/milesdevx/pactora/blob/main/app/api/auth/verify/route.ts"
click node_metadata "https://github.com/milesdevx/pactora/blob/main/lib/chain/metadata.ts"
click node_db "https://github.com/milesdevx/pactora/blob/main/lib/db/schema.ts"
click node_receipts "https://github.com/milesdevx/pactora/blob/main/lib/chain/receipts.ts"
click node_receiptsapi "https://github.com/milesdevx/pactora/blob/main/app/api/receipts/%5Bid%5D/route.ts"
click node_chainserver "https://github.com/milesdevx/pactora/blob/main/lib/chain/server.ts"
click node_telegramsettings "https://github.com/milesdevx/pactora/blob/main/app/settings/telegram/page.tsx"
click node_telegramlink "https://github.com/milesdevx/pactora/blob/main/app/api/telegram/link/route.ts"
click node_webhookroute "https://github.com/milesdevx/pactora/blob/main/app/api/telegram/webhook/route.ts"
click node_bot "https://github.com/milesdevx/pactora/blob/main/lib/telegram/webhook.ts"
click node_chainreads "https://github.com/milesdevx/pactora/blob/main/lib/telegram/chain-reads.ts"
click node_notifications "https://github.com/milesdevx/pactora/blob/main/lib/telegram/notifications.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_home,node_dashboard,node_parties toneBlue
class node_create,node_detail,node_txhook,node_terms toneAmber
class node_agreementsapi,node_evidenceapi,node_agreementapi,node_auth,node_authroutes,node_metadata,node_db toneMint
class node_telegramsettings,node_telegramlink,node_webhookroute,node_bot,node_chainreads,node_notifications toneRose
class node_receipts,node_receiptsapi,node_chainserver,node_mezo,node_telegram toneIndigo
```

## Components

### Web experience

- [Product landing](https://github.com/milesdevx/pactora/blob/main/app/page.tsx): `app/page.tsx`
- [Agreement dashboard](https://github.com/milesdevx/pactora/blob/main/app/dashboard/page.tsx): `app/dashboard/page.tsx`

### Escrow lifecycle

- [Create agreement](https://github.com/milesdevx/pactora/blob/main/app/agreements/create/page.tsx): `app/agreements/create/page.tsx`
- [Agreement actions](https://github.com/milesdevx/pactora/blob/main/app/agreements/%5Bid%5D/page.tsx): `app/agreements/[id]/page.tsx`
- [Confirmed transactions](https://github.com/milesdevx/pactora/blob/main/lib/hooks/useConfirmedTransaction.ts): `lib/hooks/useConfirmedTransaction.ts`
- [Terms and amounts](https://github.com/milesdevx/pactora/blob/main/lib/chain/terms.ts): `lib/chain/terms.ts`

### Identity and records

- [Agreement API](https://github.com/milesdevx/pactora/blob/main/app/api/agreements/route.ts): `app/api/agreements/route.ts`
- [Evidence API](https://github.com/milesdevx/pactora/blob/main/app/api/agreements/%5Bid%5D/evidence/route.ts): `app/api/agreements/[id]/evidence/route.ts`
- [Agreement detail API](https://github.com/milesdevx/pactora/blob/main/app/api/agreements/%5Bid%5D/route.ts): `app/api/agreements/[id]/route.ts`
- [Wallet authentication](https://github.com/milesdevx/pactora/blob/main/lib/security/session.ts): `lib/security/session.ts`
- [Session routes](https://github.com/milesdevx/pactora/blob/main/app/api/auth/verify/route.ts): `app/api/auth/verify/route.ts`
- [Agreement metadata](https://github.com/milesdevx/pactora/blob/main/lib/chain/metadata.ts): `lib/chain/metadata.ts`
- [PostgreSQL records](https://github.com/milesdevx/pactora/blob/main/lib/db/schema.ts): `lib/db/schema.ts`

### Telegram integration

- [Telegram settings](https://github.com/milesdevx/pactora/blob/main/app/settings/telegram/page.tsx): `app/settings/telegram/page.tsx`
- [Telegram linking API](https://github.com/milesdevx/pactora/blob/main/app/api/telegram/link/route.ts): `app/api/telegram/link/route.ts`
- [Telegram webhook route](https://github.com/milesdevx/pactora/blob/main/app/api/telegram/webhook/route.ts): `app/api/telegram/webhook/route.ts`
- [Bot command handling](https://github.com/milesdevx/pactora/blob/main/lib/telegram/webhook.ts): `lib/telegram/webhook.ts`
- [Wallet chain reads](https://github.com/milesdevx/pactora/blob/main/lib/telegram/chain-reads.ts): `lib/telegram/chain-reads.ts`
- [Alert delivery](https://github.com/milesdevx/pactora/blob/main/lib/telegram/notifications.ts): `lib/telegram/notifications.ts`

### Mezo services

- [Public receipts](https://github.com/milesdevx/pactora/blob/main/lib/chain/receipts.ts): `lib/chain/receipts.ts`
- [Receipt endpoint](https://github.com/milesdevx/pactora/blob/main/app/api/receipts/%5Bid%5D/route.ts): `app/api/receipts/[id]/route.ts`
- [Chain verification](https://github.com/milesdevx/pactora/blob/main/lib/chain/server.ts): `lib/chain/server.ts`

### Other components

- **Client and provider**
- **Mezo Testnet**
- **Telegram**

## Connections

- Client and provider → Product landing: visit (evidence: `README.md`)
- Product landing → Create agreement: start agreement (evidence: `app/page.tsx`)
- Client and provider → Create agreement: set terms (evidence: `README.md`)
- Create agreement → Confirmed transactions: submit transaction (evidence: `app/agreements/create/page.tsx`)
- Confirmed transactions → Terms and amounts: hash terms (evidence: `lib/hooks/useConfirmedTransaction.ts`)
- Create agreement → Mezo Testnet: create on-chain (evidence: `README.md`)
- Client and provider → Agreement actions: accept and fund (evidence: `README.md`)
- Agreement actions → Confirmed transactions: execute actions (evidence: `app/agreements/[id]/page.tsx`)
- Client and provider → Evidence API: register evidence (evidence: `README.md`)
- Client and provider → Agreement actions: submit and approve (evidence: `README.md`)
- Agreement actions → Mezo Testnet: release or settle (evidence: `README.md`)
- Client and provider → Agreement actions: claim timeout or refund (evidence: `README.md`)
- Agreement dashboard → Client and provider: show agreements
- Agreement API → Wallet authentication: require session (evidence: `app/api/agreements/route.ts`)
- Agreement API → Chain verification: verify chain state (evidence: `app/api/agreements/route.ts`)
- Agreement API → Agreement metadata: list verified (evidence: `app/api/agreements/route.ts`)
- Agreement API → PostgreSQL records: store metadata (evidence: `app/api/agreements/route.ts`)
- Evidence API → PostgreSQL records: read and write (evidence: `app/api/agreements/[id]/evidence/route.ts`)
- Agreement detail API → Chain verification: read party agreement (evidence: `app/api/agreements/[id]/route.ts`)
- Agreement detail API → PostgreSQL records: verify metadata (evidence: `app/api/agreements/[id]/route.ts`)
- Session routes → Wallet authentication: manage session
- Chain verification → Mezo Testnet: read contract (evidence: `lib/chain/server.ts`)
- Receipt endpoint → Chain verification: read confirmed receipt (evidence: `app/api/receipts/[id]/route.ts`)
- Receipt endpoint → Public receipts: format receipt (evidence: `app/api/receipts/[id]/route.ts`)
- Telegram settings → Telegram linking API: manage link (evidence: `app/settings/telegram/page.tsx`)
- Telegram linking API → Wallet authentication: require session (evidence: `app/api/telegram/link/route.ts`)
- Telegram linking API → PostgreSQL records: persist link token (evidence: `app/api/telegram/link/route.ts`)
- Telegram → Telegram webhook route: send updates (evidence: `README.md`)
- Telegram webhook route → Bot command handling: dispatch updates (evidence: `app/api/telegram/webhook/route.ts`)
- Bot command handling → PostgreSQL records: read and update links (evidence: `lib/telegram/webhook.ts`)
- Bot command handling → Wallet chain reads: read balances (evidence: `lib/telegram/webhook.ts`)
- Bot command handling → Alert delivery: manage alerts (evidence: `lib/telegram/webhook.ts`)
- Alert delivery → Telegram: deliver alerts
