Building Full-Stack Plugins

Zirzir features a full-stack plugin architecture. You can write custom payment gateways in TypeScript on Bun with dynamic React dashboard extensions.

---

🔌 Plugin IPC Communication Flow

sequenceDiagram
    autonumber
    participant Engine as ⚡ Zirzir Server (Rust)
    participant Worker as 🔌 Bun Plugin Worker (Node/TS)
    participant Gateway as 🏦 Remote Payment API

    Note over Engine,Worker: Server Startup: Discovery & Handshake
    Engine->>Worker: Spawn child process over stdio
    Engine->>Worker: JSON-RPC "info"
    Worker-->>Engine: Returns { code, name, currencies, config_fields }
    Engine->>Engine: Dynamically registers provider in ProviderRegistry

    Note over Engine,Gateway: Transaction Execution (Zero Downtime)
    Engine->>Worker: JSON-RPC "charge" { config, reference, amount, phone }
    Worker->>Gateway: Direct HTTPS API request
    Gateway-->>Worker: { status: "success", checkout_url: "..." }
    Worker-->>Engine: Returns { provider_txn_id, payment_url, status }

---

📁 Plugin Anatomy

Every plugin resides in its own folder inside plugins/:

plugins/my_gateway/
├── plugin.json    # Manifest, permissions & sidebar navigation
├── index.ts       # Bun backend payment driver (charge, verifyWebhook)
├── ui.tsx         # React dashboard extension component
└── dist/ui.js     # Bundled standalone frontend view

---

🧪 3-Phase Automated Test Harness

The Zirzir CLI includes an automated test harness to verify your plugin’s IPC contract:

graph LR
    P1[Phase 1: Manifest Inspection<br/>plugin.json valid schema] --> P2[Phase 2: RPC Handshake<br/>stdio JSON-RPC 'info' method]
    P2 --> P3[Phase 3: Mock Charge Execution<br/>stdio JSON-RPC 'charge' simulation]
    P3 --> PASS[✅ Plugin Ready for Production]

    style P1 fill:#1e293b,stroke:#38bdf8,color:#fff
    style P2 fill:#1e293b,stroke:#f59e0b,color:#fff
    style P3 fill:#1e293b,stroke:#10b981,color:#fff
    style PASS fill:#047857,stroke:#10b981,color:#fff

zirzir plugin test plugins/santimpay