# amant-creator/verify_payments architecture

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

- Interactive diagram: https://gitdiagram.com/amant-creator/verify_payments
- Repository: https://github.com/amant-creator/verify_payments

## Overview

This is a Next.js UPI checkout and merchant payment-verification system. Customers create an order, open its checkout to pay by UPI deep link or QR, and return to a live verification page. The merchant approves or rejects through Telegram or the admin dashboard; the customer sees the resulting status. Persisted timestamps drive two verification countdown stages and an overdue manual-review state. The graph includes the documented dashboard and security capabilities; some route wiring is not shown in the excerpts, so those relationships are omitted where they cannot be evidenced.

Main entry points: [`app/checkout/[orderId]/page.tsx`](https://github.com/amant-creator/verify_payments/blob/main/app/checkout/%5BorderId%5D/page.tsx) (Checkout Session), [`lib/db.ts`](https://github.com/amant-creator/verify_payments/blob/main/lib/db.ts) (Order Repository), [`app/api/orders/route.ts`](https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/route.ts) (Order API), [`components/VerificationView.tsx`](https://github.com/amant-creator/verify_payments/blob/main/components/VerificationView.tsx) (Verification Display)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer Checkout"]
  node_storefront["Order Storefront<br/>[page.tsx]"]
  node_checkout_page["Checkout Session<br/>[page.tsx]"]
  node_checkout_view["Payment Display<br/>[CheckoutView.tsx]"]
  node_verification_view["Verification Display"]
  node_countdown["Countdown Timer<br/>[CountdownTimer.tsx]"]
  node_success["Success Result<br/>[SuccessView.tsx]"]
  node_rejected["Rejected Result<br/>[RejectedView.tsx]"]
end

subgraph group_verification["Verification Workflow"]
  node_order_api["Order API<br/>[route.ts]"]
  node_return_api["Return Handler<br/>[route.ts]"]
  node_launch_api["Launch Handler<br/>[route.ts]"]
  node_utr_api["UTR Handler<br/>[route.ts]"]
  node_order_api_detail["Order Status API<br/>[route.ts]"]
  node_stream_api["SSE Stream<br/>[route.ts]"]
end

subgraph group_merchant["Merchant Decisions"]
  node_admin["Admin Dashboard<br/>[page.tsx]"]
  node_decision_api["Decision Handler<br/>[route.ts]"]
  node_webhook["Telegram Webhook<br/>[route.ts]"]
  node_debug_api["Admin Debug API<br/>[route.ts]"]
end

subgraph group_services["Runtime Services"]
  node_upi["UPI Formatting<br/>[upi.ts]"]
  node_timer["Timer Logic<br/>[timer.ts]"]
  node_telegram["Telegram Service<br/>[telegram.ts]"]
  node_db["Order Repository<br/>[db.ts]"]
  node_firebase_client["Customer Firebase<br/>[firebase.ts]"]
  node_auth["Admin Secret Check<br/>[auth.ts]"]
  node_rules["Firestore Rules<br/>[firestore.rules]"]
  node_order_types["Order Model<br/>[order.ts]"]
end

node_customer(("Customer"))
node_upi_app(("UPI App"))
node_telegram_platform["Telegram Bot API"]
node_firestore[("Firestore")]

node_customer -->|"opens"| node_storefront
node_storefront -->|"opens checkout"| node_checkout_page
node_customer -->|"creates order"| node_order_api
node_order_api -->|"creates order"| node_db
node_order_api -->|"notifies merchant"| node_telegram
node_checkout_page -->|"renders payment"| node_checkout_view
node_checkout_view -->|"formats amount"| node_upi
node_checkout_page -->|"builds payment URI"| node_upi
node_customer -->|"launches payment"| node_upi_app
node_checkout_page -.->|"records launch"| node_launch_api
node_customer -->|"returns to"| node_checkout_page
node_checkout_page -->|"reports return"| node_return_api
node_return_api -->|"records verification"| node_db
node_checkout_page -->|"subscribes to order"| node_firebase_client
node_checkout_page -->|"derives countdown"| node_timer
node_checkout_page -->|"renders pending state"| node_verification_view
node_verification_view -->|"renders timer"| node_countdown
node_verification_view -->|"formats amount"| node_upi
node_verification_view -.->|"submits reference"| node_utr_api
node_checkout_page -->|"renders approval"| node_success
node_checkout_page -->|"renders rejection"| node_rejected
node_admin -->|"derives countdown"| node_timer
node_admin -.->|"lists orders"| node_order_api
node_admin -.->|"submits decision"| node_decision_api
node_decision_api -->|"records decision"| node_db
node_decision_api -->|"checks secret"| node_auth
node_webhook -->|"records decision"| node_db
node_webhook -->|"updates message"| node_telegram
node_telegram -->|"calls bot API"| node_telegram_platform
node_debug_api -->|"checks storage"| node_db
node_db -->|"reads and writes"| node_firestore
node_firebase_client -.->|"subscribes"| node_firestore
node_rules -->|"restricts access"| node_firestore
node_order_api -->|"creates model"| node_order_types

click node_storefront "https://github.com/amant-creator/verify_payments/blob/main/app/page.tsx"
click node_order_api "https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/route.ts"
click node_checkout_page "https://github.com/amant-creator/verify_payments/blob/main/app/checkout/%5BorderId%5D/page.tsx"
click node_checkout_view "https://github.com/amant-creator/verify_payments/blob/main/components/CheckoutView.tsx"
click node_verification_view "https://github.com/amant-creator/verify_payments/blob/main/components/VerificationView.tsx"
click node_countdown "https://github.com/amant-creator/verify_payments/blob/main/components/CountdownTimer.tsx"
click node_success "https://github.com/amant-creator/verify_payments/blob/main/components/SuccessView.tsx"
click node_rejected "https://github.com/amant-creator/verify_payments/blob/main/components/RejectedView.tsx"
click node_upi "https://github.com/amant-creator/verify_payments/blob/main/lib/upi.ts"
click node_return_api "https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/return/route.ts"
click node_launch_api "https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/launch/route.ts"
click node_utr_api "https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/utr/route.ts"
click node_order_api_detail "https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/route.ts"
click node_stream_api "https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/stream/route.ts"
click node_timer "https://github.com/amant-creator/verify_payments/blob/main/lib/timer.ts"
click node_admin "https://github.com/amant-creator/verify_payments/blob/main/app/admin/page.tsx"
click node_decision_api "https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/decision/route.ts"
click node_webhook "https://github.com/amant-creator/verify_payments/blob/main/app/api/telegram/webhook/route.ts"
click node_debug_api "https://github.com/amant-creator/verify_payments/blob/main/app/api/admin/debug/route.ts"
click node_telegram "https://github.com/amant-creator/verify_payments/blob/main/lib/telegram.ts"
click node_db "https://github.com/amant-creator/verify_payments/blob/main/lib/db.ts"
click node_firebase_client "https://github.com/amant-creator/verify_payments/blob/main/lib/firebase.ts"
click node_auth "https://github.com/amant-creator/verify_payments/blob/main/lib/auth.ts"
click node_rules "https://github.com/amant-creator/verify_payments/blob/main/firestore.rules"
click node_order_types "https://github.com/amant-creator/verify_payments/blob/main/types/order.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_storefront,node_checkout_page,node_checkout_view,node_verification_view,node_countdown,node_success,node_rejected toneBlue
class node_order_api,node_return_api,node_launch_api,node_utr_api,node_order_api_detail,node_stream_api,node_firestore toneAmber
class node_admin,node_decision_api,node_webhook,node_debug_api,node_telegram_platform toneMint
class node_upi,node_timer,node_telegram,node_db,node_firebase_client,node_auth,node_rules,node_order_types toneRose
class node_customer,node_upi_app toneIndigo
```

## Components

### Customer Checkout

- [Order Storefront](https://github.com/amant-creator/verify_payments/blob/main/app/page.tsx): `app/page.tsx`
- [Checkout Session](https://github.com/amant-creator/verify_payments/blob/main/app/checkout/%5BorderId%5D/page.tsx): `app/checkout/[orderId]/page.tsx`
- [Payment Display](https://github.com/amant-creator/verify_payments/blob/main/components/CheckoutView.tsx): `components/CheckoutView.tsx`
- [Verification Display](https://github.com/amant-creator/verify_payments/blob/main/components/VerificationView.tsx): `components/VerificationView.tsx`
- [Countdown Timer](https://github.com/amant-creator/verify_payments/blob/main/components/CountdownTimer.tsx): `components/CountdownTimer.tsx`
- [Success Result](https://github.com/amant-creator/verify_payments/blob/main/components/SuccessView.tsx): `components/SuccessView.tsx`
- [Rejected Result](https://github.com/amant-creator/verify_payments/blob/main/components/RejectedView.tsx): `components/RejectedView.tsx`

### Verification Workflow

- [Order API](https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/route.ts): `app/api/orders/route.ts`
- [Return Handler](https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/return/route.ts): `app/api/orders/[orderId]/return/route.ts`
- [Launch Handler](https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/launch/route.ts): `app/api/orders/[orderId]/launch/route.ts`
- [UTR Handler](https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/utr/route.ts): `app/api/orders/[orderId]/utr/route.ts`
- [Order Status API](https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/route.ts): `app/api/orders/[orderId]/route.ts`
- [SSE Stream](https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/stream/route.ts): `app/api/orders/[orderId]/stream/route.ts`

### Merchant Decisions

- [Admin Dashboard](https://github.com/amant-creator/verify_payments/blob/main/app/admin/page.tsx): `app/admin/page.tsx`
- [Decision Handler](https://github.com/amant-creator/verify_payments/blob/main/app/api/orders/%5BorderId%5D/decision/route.ts): `app/api/orders/[orderId]/decision/route.ts`
- [Telegram Webhook](https://github.com/amant-creator/verify_payments/blob/main/app/api/telegram/webhook/route.ts): `app/api/telegram/webhook/route.ts`
- [Admin Debug API](https://github.com/amant-creator/verify_payments/blob/main/app/api/admin/debug/route.ts): `app/api/admin/debug/route.ts`

### Runtime Services

- [UPI Formatting](https://github.com/amant-creator/verify_payments/blob/main/lib/upi.ts): `lib/upi.ts`
- [Timer Logic](https://github.com/amant-creator/verify_payments/blob/main/lib/timer.ts): `lib/timer.ts`
- [Telegram Service](https://github.com/amant-creator/verify_payments/blob/main/lib/telegram.ts): `lib/telegram.ts`
- [Order Repository](https://github.com/amant-creator/verify_payments/blob/main/lib/db.ts): `lib/db.ts`
- [Customer Firebase](https://github.com/amant-creator/verify_payments/blob/main/lib/firebase.ts): `lib/firebase.ts`
- [Admin Secret Check](https://github.com/amant-creator/verify_payments/blob/main/lib/auth.ts): `lib/auth.ts`
- [Firestore Rules](https://github.com/amant-creator/verify_payments/blob/main/firestore.rules): `firestore.rules`
- [Order Model](https://github.com/amant-creator/verify_payments/blob/main/types/order.ts): `types/order.ts`

### Other components

- **Customer**
- **UPI App**
- **Telegram Bot API**
- **Firestore**

## Connections

- Customer → Order Storefront: opens (evidence: `README.md`)
- Order Storefront → Checkout Session: opens checkout (evidence: `README.md`)
- Customer → Order API: creates order (evidence: `README.md`)
- Order API → Order Repository: creates order (evidence: `app/api/orders/route.ts`)
- Order API → Telegram Service: notifies merchant (evidence: `app/api/orders/route.ts`)
- Checkout Session → Payment Display: renders payment (evidence: `app/checkout/[orderId]/page.tsx`)
- Payment Display → UPI Formatting: formats amount (evidence: `components/CheckoutView.tsx`)
- Checkout Session → UPI Formatting: builds payment URI (evidence: `README.md`)
- Customer → UPI App: launches payment (evidence: `README.md`)
- Checkout Session → Launch Handler: records launch
- Customer → Checkout Session: returns to (evidence: `README.md`)
- Checkout Session → Return Handler: reports return (evidence: `app/checkout/[orderId]/page.tsx`)
- Return Handler → Order Repository: records verification (evidence: `app/api/orders/[orderId]/return/route.ts`)
- Checkout Session → Customer Firebase: subscribes to order (evidence: `app/checkout/[orderId]/page.tsx`)
- Checkout Session → Timer Logic: derives countdown (evidence: `app/checkout/[orderId]/page.tsx`)
- Checkout Session → Verification Display: renders pending state (evidence: `app/checkout/[orderId]/page.tsx`)
- Verification Display → Countdown Timer: renders timer (evidence: `components/VerificationView.tsx`)
- Verification Display → UPI Formatting: formats amount (evidence: `components/VerificationView.tsx`)
- Verification Display → UTR Handler: submits reference
- Checkout Session → Success Result: renders approval (evidence: `app/checkout/[orderId]/page.tsx`)
- Checkout Session → Rejected Result: renders rejection (evidence: `app/checkout/[orderId]/page.tsx`)
- Admin Dashboard → Timer Logic: derives countdown (evidence: `app/admin/page.tsx`)
- Admin Dashboard → Order API: lists orders
- Admin Dashboard → Decision Handler: submits decision
- Decision Handler → Order Repository: records decision (evidence: `app/api/orders/[orderId]/decision/route.ts`)
- Decision Handler → Admin Secret Check: checks secret (evidence: `app/api/orders/[orderId]/decision/route.ts`)
- Telegram Webhook → Order Repository: records decision (evidence: `app/api/telegram/webhook/route.ts`)
- Telegram Webhook → Telegram Service: updates message (evidence: `app/api/telegram/webhook/route.ts`)
- Telegram Service → Telegram Bot API: calls bot API (evidence: `lib/telegram.ts`)
- Admin Debug API → Order Repository: checks storage (evidence: `app/api/admin/debug/route.ts`)
- Order Repository → Firestore: reads and writes (evidence: `lib/db.ts`)
- Customer Firebase → Firestore: subscribes
- Firestore Rules → Firestore: restricts access (evidence: `README.md`)
- Order API → Order Model: creates model (evidence: `app/api/orders/route.ts`)
