> ## Documentation Index
> Fetch the complete documentation index at: https://docs.winstory.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations Runbook

> Playbooks for diagnosing and resolving common production issues.

## Purpose

This runbook provides **step-by-step procedures** to investigate and resolve the most common incidents on Winstory.io.

It is meant for:

* On-call engineers
* SRE / DevOps

## 1. Dashboard or MyWin not loading

**Symptoms:**

* `/mywin/creations` spins indefinitely
* Dashboard shows "Failed to fetch"

**Checklist:**

1. Check `system_error_logs` in Supabase for recent entries:
   * Filter by `errorType = 'ApiError'` and `created_at DESC`
2. Verify `/api/campaigns/dashboard` and `/api/campaigns/moderation`:
   * Call them directly with a known `campaignId` / `walletAddress`
3. If DB errors:
   * Check Supabase status and connection limits
4. If timeouts:
   * Verify recent changes in metrics or dashboard code

## 2. Payments failing (Stripe or Crypto)

**Symptoms:**

* Campaigns not created after payment
* Creators report "Payment taken but no campaign"

**Checklist:**

1. Search `system_error_logs` for `errorType = 'PaymentError'` or `severity = 'critical'`.
2. For crypto:
   * Use `/api/cron/monitor-onchain` or manually call `verifyCryptoTransactionOnChain` (see `lib/crypto-payment-verification.ts`).
3. For Stripe:
   * Check `/api/payment/webhook` logs and Stripe dashboard events.
4. Verify `payments` table:
   * `provider_id` (tx hash or Stripe payment id)
   * `status` (should be `ONCHAIN` or `SUCCEEDED`)

## 3. On-chain inconsistencies

**Symptoms:**

* Dashboard shows mismatched status vs actual blockchain
* Rewards not distributed as expected

**Checklist:**

1. Run `/api/cron/monitor-onchain` manually and inspect response.
2. Check `campaign_blockchain_mapping` vs on-chain:
   * `blockchain_campaign_id`
   * `creation_tx_hash`
3. Use the Base Sepolia testing scripts in `scripts/`:
   * `npx hardhat run scripts/test-base-sepolia-e2e.js --network baseSepolia`

## 4. Rate limiting issues (429)

**Symptoms:**

* Users see "Rate limit exceeded" on API calls

**Checklist:**

1. Confirm origin:
   * App-level middleware (`middleware.ts`)
   * External WAF or CDN rules
2. For app-level:
   * Adjust `MAX_REQUESTS` / `WINDOW_MS` in `middleware.ts`
   * Deploy and monitor `429` frequency

## 5. General error escalation

If an incident cannot be resolved quickly:

* Escalate with:
  * Recent logs from `system_error_logs`
  * Offending endpoint(s) and payload samples
  * Timeline of events (deploys, config changes)