┌─────────────────────────────────────────────────────────────────────────────┐
│                           PRESENTATION LAYER                                │
│   React 19 + TypeScript + Vite + Tailwind CSS v4 + Shadcn UI + GSAP        │
│   • Interactive Chat Interface      • Live MCP Data Explorer                │
│   • Webhook Automation Suite        • Dynamic UPI QR & Checkout Modal       │
└───────────────────────┬─────────────────────────────┬───────────────────────┘
                        │                             │
                        ▼                             ▼
┌─────────────────────────────────┐       ┌───────────────────────────────────┐
│     AI ORCHESTRATION LAYER      │       │     CLOUD PERSISTENCE LAYER       │
│  • Google Gemini 2.5 Flash      │       │  • Firebase Authentication        │
│  • Dynamic Function Calling     │       │  • Cloud Firestore Sessions       │
│  • Real-Time Tool Execution     │       │  • Real-Time Chat Synchronization │
└───────────────┬─────────────────┘       └───────────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     MODEL CONTEXT PROTOCOL (MCP) LAYER                      │
│   • Stdio Transport MCP Server (@modelcontextprotocol/sdk)                  │
│   • In-Browser MCP Client with Vite Reverse Proxy (/api/razorpay)           │
│   • 8+ Standardized Tools (Payments, Orders, Refunds, Links, Settlements)   │
└───────────────────────────────────────┬─────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          RAZORPAY INTEGRATION TIER                          │
│   • Live Razorpay REST API (v1)      • Webhook Ingestion Engine             │
│   • Standard Checkout.js Modal       • HMAC-SHA256 Signature Verification   │
└─────────────────────────────────────────────────────────────────────────────┘

flowchart TD
    subgraph Client["🖥️ Client Tier (Browser)"]
        UI["React 19 SPA<br/>(Dashboard / Chat / Explorer)"]
        Renderer["Markdown Renderer<br/>(UPI QR & Checkout Buttons)"]
        HookUI["Webhook Automation Suite<br/>(Event Simulator & Feed)"]
    end

    subgraph Orchestrator["🧠 AI Orchestration Tier"]
        Gemini["Google Gemini 2.5 Flash<br/>(Function Calling & Tool Dispatcher)"]
    end

    subgraph MCP["🔌 Model Context Protocol (MCP) Tier"]
        StdioMCP["MCP Stdio Server<br/>(mcp-server/index.mjs)"]
        ClientMCP["MCP Web Client<br/>(src/services/mcpClient.ts)"]
        ToolList["MCP Tools:<br/>• get_payment • list_payments<br/>• get_order • create_order<br/>• create_payment_link • get_refunds"]
    end

    subgraph RazorpayGateway["💳 Razorpay Core & Banking Tier"]
        RzpAPI["Razorpay REST API v1<br/>(api.razorpay.com)"]
        RzpCheckout["Razorpay Checkout.js<br/>(Native Modal)"]
        WebhookIn["Vite Webhook Middleware<br/>(/api/webhooks/razorpay)"]
    end

    subgraph Persistence["🔥 Persistence Tier"]
        FBAuth["Firebase Auth<br/>(Google & Email/Password)"]
        Firestore["Cloud Firestore<br/>(Sessions & Message History)"]
    end

    UI --> Gemini
    Gemini --> ToolList
    ToolList --> ClientMCP
    ToolList --> StdioMCP
    ClientMCP --> RzpAPI
    StdioMCP --> RzpAPI
    Renderer --> RzpCheckout
    RzpCheckout -.->|Triggers Event| WebhookIn
    WebhookIn -->|Stream Event| UI
    UI <--> Firestore
    UI <--> FBAuth

sequenceDiagram
    autonumber
    actor Merchant as 👨‍💼 Merchant / Support User
    participant UI as 💬 Chat Interface (React)
    participant LLM as 🤖 LLM (Google Gemini 2.5 Flash)
    participant MCP as 🔌 Razorpay MCP Client
    participant RZP as 💳 Razorpay Live API

    Merchant->>UI: "What's the status of order order_TXGPnb2izSqLLF?"
    UI->>LLM: Send message history + available MCP Tool Schemas
    Note over LLM: LLM detects intent & invokes get_order_details(order_id: "order_TXGPnb2izSqLLF")
    LLM-->>UI: Return Function Call Request (Tool Name + Args)
    UI->>MCP: Execute mcpGetOrder("order_TXGPnb2izSqLLF")
    MCP->>RZP: GET https://api.razorpay.com/v1/orders/order_TXGPnb2izSqLLF
    RZP-->>MCP: 200 OK (amount: 149900, status: "created", amount_due: 149900)
    MCP-->>UI: Formatted JSON Result { status: "created", due: "₹1,499.00" }
    UI->>LLM: Send Tool Execution Result back to LLM context
    Note over LLM: Synthesizes live data into actionable markdown with payment recommendations
    LLM-->>UI: Markdown Response with Status Table & Action Options
    UI-->>Merchant: Displays clean status card with "Generate Payment Link" prompt

flowchart TD
    Start(["⚡ Webhook Event Occurs<br/>(e.g., payment.failed, order.paid)"]) --> Ingest["Incoming POST<br/>/api/webhooks/razorpay"]
    
    Ingest --> SigCheck{"Verify Signature?<br/>x-razorpay-signature"}
    SigCheck -- "HMAC-SHA256 Mismatch" --> Reject["❌ 400 Bad Request<br/>Log Security Anomaly"]
    SigCheck -- "Verified / Dev Mode" --> Buffer["Store in Rolling Memory Buffer<br/>(Last 50 Events)"]

    Buffer --> EventType{"Event Type"}

    EventType -- "order.paid / payment.captured" --> PaidFlow["🟢 Paid Event Detected"]
    PaidFlow --> TriagePaid["AI Triage: Generate Order Fulfillment Advice<br/>& Tax Invoice Recommendation"]
    TriagePaid --> PushPaid["Broadcast Celebration Card into Active Chat<br/>Status: CAPTURED | Amount Paid"]

    EventType -- "payment.failed" --> FailFlow["🔴 Failure Event Detected"]
    FailFlow --> TriageFail["AI Triage: Extract error_code & error_description<br/>(e.g., BAD_REQUEST_ERROR / Bank Decline)"]
    TriageFail --> GenRecovery["Formulate Recovery Message & Actionable Advisory<br/>'Customer entered wrong OTP. Send UPI retry link.'"]
    GenRecovery --> PushFail["Broadcast Emergency Alert Card into Active Chat<br/>With Instant 'Generate Recovery Link' CTA"]

    EventType -- "dispute.created" --> DispFlow["⚠️ Chargeback Dispute Filed"]
    DispFlow --> TriageDisp["AI Triage: Determine Evidence Deadline<br/>& List Required Proof Documents"]
    TriageDisp --> PushDisp["Broadcast Urgent Dispute Card to Merchant"]

flowchart LR
    A["Merchant / User clicks<br/>'Send Recovery Link'<br/>or asks in Chat"] --> B["LLM invokes MCP Tool<br/>create_payment_link"]
    
    B --> C["Fetch Order Details<br/>to ensure exact amount_due"]
    
    C --> D["POST /v1/payment_links<br/>• Amount in Paise<br/>• Customer Name & Contact<br/>• Auto-notification Flags"]
    
    D --> E["Razorpay returns:<br/>• Payment Link ID<br/>• Hosted URL (rzp.io/l/...)"]
    
    E --> F["Dynamic UPI QR Generator<br/>Constructs scannable QR payload"]
    
    F --> G["Render Interactive Card in Chat:<br/>1. 📱 Scannable UPI QR (GPay, PhonePe, Paytm)<br/>2. 💳 One-Click 'Pay on This Device' Button<br/>3. 🔗 Shareable Payment Link"]
    
    G --> H{"Customer Pays via<br/>UPI or Card?"}
    H -->|Payment Captured| I["⚡ Live Webhook Received<br/>Chat updates to PAID instantly"]

flowchart TD
    Upload["📁 User uploads File into Chat<br/>(.json, .txt, .pdf, .csv, .log, image)"] --> Parse{"File Type Detection"}
    
    Parse -- "JSON / TXT / CSV / Log" --> TextRead["Extract Full Text Payload<br/>(Up to 25,000 characters)"]
    Parse -- "Image / Screenshot" --> ImgRead["Generate Object URL Preview<br/>+ Extract Visual Metadata"]
    Parse -- "PDF Document" --> DocRead["Parse Document Content & Attach Context"]

    TextRead --> StructMatch{"Contains Invoice Data?"}
    ImgRead --> StructMatch
    DocRead --> StructMatch

    StructMatch -- "Yes (e.g. INV-2026-09-002)" --> ExtractData["Identify Key Fields:<br/>• Order ID (order_...)<br/>• Amount (₹1,499.00)<br/>• GSTIN & Line Items<br/>• Customer Email & Phone"]

    ExtractData --> MCPVerify["Automatic MCP Verification:<br/>Execute get_order(order_id)"]
    
    MCPVerify --> CrossCheck{"Compare Extracted Data vs.<br/>Live Razorpay Records"}
    
    CrossCheck -- "Discrepancy Found" --> WarnUser["⚠️ Alert: Invoice amount does not match<br/>live order due amount!"]
    CrossCheck -- "Exact Match" --> Confirm["✅ Verified: Order exists in Razorpay<br/>Display Breakdown & Payment State"]
    
    Confirm --> RenderCard["Interactive Chat Card:<br/>• Tax Invoice Details<br/>• Payment Status<br/>• One-Click Action Trigger"]

flowchart TD
    subgraph CoreEngine["Razorpay Model Context Protocol Core"]
        Tools["MCP Tools Implementation<br/>• list_payments • get_payment<br/>• list_orders • get_order<br/>• create_order • create_payment_link<br/>• list_refunds • get_refund<br/>• create_refund • list_settlements"]
    end

    subgraph Transport1["Transport 1: Local Stdio (CLI / IDEs)"]
        Stdio["StdioServerTransport<br/>(mcp-server/index.mjs)"]
        StdioClients["Compatible Clients:<br/>• Claude Desktop<br/>• Cursor AI<br/>• Antigravity IDE<br/>• Any MCP Stdio Client"]
    end

    subgraph Transport2["Transport 2: In-Browser Web SDK (Vite SPA)"]
        WebClient["Client MCP Service<br/>(src/services/mcpClient.ts)"]
        ViteProxy["Vite HTTP Proxy<br/>/api/razorpay ➔ api.razorpay.com"]
        BrowserUI["Web Application UI<br/>(Interactive Dashboard)"]
    end

    subgraph RazorpayCloud["Razorpay API v1"]
        APIGateway["https://api.razorpay.com/v1"]
    end

    StdioClients <== "JSON-RPC 2.0 via Stdin/Stdout" ==> Stdio
    Stdio <==> Tools
    Tools <== "Direct HTTPS (Basic Auth)" ==> APIGateway

    BrowserUI <==> WebClient
    WebClient <== "Basic Auth / Fetch" ==> ViteProxy
    ViteProxy <== "Reverse Proxied HTTPS" ==> APIGateway

razorpay-agent/
├── .agents/
│   ├── mcp_config.json                 # Antigravity IDE MCP Server Configuration
│   └── plugins/razorpay/
│       ├── mcp_config.json             # Namespaced plugin configuration
│       └── plugin.json                 # Razorpay plugin manifest
├── mcp-server/
│   └── index.mjs                       # Standalone Node.js MCP Server (Stdio Transport)
├── public/
│   ├── razorpay.svg                    # Razorpay brand assets
│   └── Untitled design (14).svg
├── scripts/
│   └── create_test_orders.mjs          # CLI script to generate live unpaid test orders
├── src/
│   ├── components/
│   │   ├── ui/                         # Shadcn UI component library (Buttons, Dialogs, etc.)
│   │   ├── MarkdownRenderer.tsx        # Markdown renderer with live UPI QR & Payment buttons
│   │   ├── theme-provider.tsx          # Dark / Light theme provider
│   │   ├── WebhookAutomationModal.tsx  # Webhook automation drawer modal
│   │   └── WebhookAutomationPage.tsx   # Dedicated full-page Webhook Ingestion & Triage Suite
│   ├── lib/
│   │   └── firebase.ts                 # Firebase app, auth, and firestore initialization
│   ├── pages/
│   │   ├── Auth.tsx                    # Animated split-screen sign-in / sign-up (GSAP)
│   │   ├── Dashboard.tsx               # Main application dashboard, chat, and MCP explorer
│   │   └── Landing.tsx                 # Clean product landing page with quick-start action
│   ├── services/
│   │   ├── gemini.ts                   # Google Gemini Flash client with function declarations
│   │   ├── firebaseChat.ts             # Firestore session sync & migration utilities
│   │   ├── mcpClient.ts                # In-browser MCP client calling Razorpay REST API
│   │   ├── razorpayCheckout.ts         # Razorpay Checkout.js wrapper with webhook triggers
│   │   └── webhookAutomation.ts        # Webhook ingestion, signature verification & AI triage
│   ├── App.tsx                         # Client-side routing configuration
│   ├── index.css                       # Tailwind CSS v4 design tokens & base typography
│   └── main.tsx                        # Application mount entrypoint
├── .env.example                        # Template for environment credentials
├── index.html                          # HTML template containing Razorpay checkout script
├── mcp_config.json                     # Root MCP configuration for desktop clients
├── package.json                        # NPM scripts and project dependencies
├── tsconfig.json                       # TypeScript compiler configuration
└── vite.config.ts                      # Vite configuration with webhook receiver & reverse proxies

cp .env.example .env

# Razorpay Credentials (from https://dashboard.razorpay.com/app/keys)
RAZORPAY_KEY_ID=rzp_test_YOUR_KEY_ID
RAZORPAY_KEY_SECRET=YOUR_KEY_SECRET

# Vite Client Credentials
VITE_RAZORPAY_KEY_ID=rzp_test_YOUR_KEY_ID
VITE_RAZORPAY_KEY_SECRET=YOUR_KEY_SECRET

# Webhook Secret (Matches the secret configured in Razorpay Webhooks dashboard)
VITE_RAZORPAY_WEBHOOK_SECRET=rzp_whsec_auto_998877

# AI Orchestration Keys
VITE_GEMINI_API_KEY=AIzaSyYOUR_KEY

npm run dev

npm run mcp:server

{
  "mcpServers": {
    "razorpay": {
      "command": "node",
      "args": ["c:/Users/Shreyansh/Desktop/razorpay-agent/mcp-server/index.mjs"],
      "env": {
        "RAZORPAY_KEY_ID": "rzp_test_YOUR_KEY_ID",
        "RAZORPAY_KEY_SECRET": "YOUR_KEY_SECRET"
      }
    }
  }
}

{
  "mcpServers": {
    "razorpay": {
      "command": "node",
      "args": ["./mcp-server/index.mjs"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

node scripts/create_test_orders.mjs