Integration Patterns

Vetty integrates with three external systems today: Razorpay (payments), an email provider (Mailgun or AWS SES, switchable per tenant), and dompdf (in-process PDF rendering). Two more channels (SMS, Push) are scaffolded but not implemented.

Notification driver abstraction

The single contract App\Notifications\Contracts\NotificationDriver lets every outbound message take the same code path:

Job  ──▶  TemplateRenderer  ──▶  OutboundMessage  ──▶  DriverManager  ──▶  Mailgun / SES / Mail / Log
                                                                ▲
                                                                │
                                                       resolved per request
                                                       from config + service_settings

See Notifications module for the operational story. Architecturally:

• Per-tenant overrides — service_settings carries optional mail.driver, mail.from.address, etc. for a tenant. The NotificationDriverManager falls back to platform config('notifications.*') values when there's no tenant override.
• Encrypted secrets — provider keys live in service_settings.value with an encrypted cast, so dumps never expose them in plaintext.
• Driver health — each driver implements a name() method; the admin UI hits GET /reminders/health to verify a driver is configured.
• Future channels — SMS and Push providers are listed in the admin UI scaffold but the corresponding Driver implementations don't exist yet (audit P3).

Razorpay payments

App\Services\Payments\RazorpayGateway wraps the official razorpay/razorpay SDK. It implements the same PaymentGateway contract that future Stripe / PayU adapters can plug into.

Order + verify flow (vetty → Razorpay)

1. POST /me/invoices/{id}/razorpay/order
   ──▶ RazorpayGateway::createOrder(amount, currency, receipt)
   ──▶ Razorpay API
   ◀── {order_id, amount, currency}

2. App launches Razorpay SDK with order_id + key
   ──▶ User completes payment on the SDK sheet
   ◀── SDK returns {payment_id, signature}

3. POST /me/invoices/{id}/razorpay/verify
   ──▶ RazorpayGateway::verifyPaymentSignature({order_id, payment_id, signature})
   ──▶ HMAC check
   ──▶ Persist Payment row, recompute balance

Webhook flow (Razorpay → backend)

1. Razorpay POSTs to /api/v1/webhooks/razorpay with the payload + signature
2. RazorpayGateway::verifyWebhookSignature(rawBody, signature) using RAZORPAY_WEBHOOK_SECRET
3. Dispatch on event:
   - payment.captured  ──▶ ensure Payment row exists / is captured
   - payment.failed    ──▶ stamp the failure reason
   - refund.processed  ──▶ reflect refund on the original Payment
4. Audit-log the event

Critical audit items

The audit (AUDIT.md §5) flags two P0 trust-boundary issues:

1. The verify endpoint validates the HMAC over the (order_id, payment_id, signature) triple but doesn't re-fetch the canonical amount from Razorpay — an attacker who hijacks a small payment id can mark a large invoice paid. Fix: call payments/{id} from the Razorpay client inside verify() and assert against invoice.balance_due * 100.
2. The webhook trusts payload.amount — same mitigation.

A third issue: when RAZORPAY_WEBHOOK_SECRET is unset the gateway silently rejects all events. Fail loudly.

These are scheduled into Wave 1 of the audit's implementation plan.

PDF generation (dompdf)

In-process via barryvdh/laravel-dompdf. Two generators today:

• App\Support\Receipts\ReceiptPdfGenerator — for invoice receipts. Accepts an Invoice plus a regenerate flag; caches the result on the model.
• Owner portal PDF helpers in Owner\OwnerPortalController — vaccination certificate, statement, pet passport. Generated on demand, no caching.

PDFs are streamed back through Laravel rather than served from disk, so every fetch re-runs the auth + permission checks.

Webhooks: shared trust boundary

Razorpay is the only inbound webhook today, but the audit recommends a small WebhookController base class that enforces:

• Signature verification (each provider's HMAC scheme).
• Idempotency key (don't double-apply on replay).
• Re-fetch from upstream before mutating local state.
• Raw payload size cap (DoS guard).
• Audit-log on receipt regardless of whether processing succeeded.

This becomes more relevant once Mailgun bounces, Twilio inbound SMS, and FCM push delivery receipts wire in.

Mail providers

MailgunDriver and SesDriver are the production-ready implementations. MailDriver (Laravel mail-stack passthrough) is used by tests and works with the array driver so feature tests can assert on outbound messages without sending.

The dev-only endpoint POST /api/v1/dev/mail-test is wired to bypass the queue and send a hand-built test message through the active driver — useful for verifying creds without going through the full reminder flow. The route only registers when APP_ENV=local; the controller also guards.

Flutter HTTP clients

Both Flutter apps share a thin ApiClient wrapper in core/api/. Conventions:

• Bearer token from auth_store.dart is attached per request.
• 401 responses clear the local session immediately (no token refresh — audit P1).
• Errors are surfaced as a typed ApiException with the backend's message and errors fields.

The audit calls out (P0) the lack of certificate pinning on both apps.

React HTTP client

ui/src/services/index.js carries the React app's HTTP wrapper. Audit (P1) calls out:

• The Bearer header reads getAccessToken() once at construction time — token rotation breaks subsequent requests.
• Tokens live in localStorage (XSS-stealable). Recommended fix: backend issues an httpOnly Secure cookie; frontend never sees the token.
• No CSRF token on POST forms — Sanctum's stateful flow needs the XSRF-TOKEN cookie + header.

Roadmap

• Stripe + PayU adapters behind the PaymentGateway contract.
• Twilio + MSG91 SMS drivers.
• FCM + APNS push drivers.
• WhatsApp Business API.
• GST e-invoicing (India NIC) for India-mode tenants.
• Mailgun bounce webhook → auto-opt-out.

See AUDIT.md §6 (notifications), §5 (billing/payments), and §8 (frontends) for the full punch-list.