Learn Micro-SaaS Architecture & Copy-Paste Prompts

# Dodo prepaid credits — Punchline Lab POC

This POC wires **Dodo Payments credit entitlements** to the joke generator. Official references:

- [Integration guide](https://docs.dodopayments.com/developer-resources/integration-guide)
- [Prepaid email / ledger pattern](https://docs.dodopayments.com/developer-resources/build-a-prepaid-email-service-with-credit-based-billing)
- [Credit-based API platform](https://docs.dodopayments.com/developer-resources/build-an-ai-api-platform-with-credit-based-billing)

## What Dodo handles (source of truth)

| Concern | Dodo |
| --- | --- |
| Checkout & payment | Checkout Sessions API, test/live mode |
| Customer record | `cus_*` created via checkout |
| Credit balance | Credit entitlement (`cde_*`) balance API |
| Granting credits on purchase | Product → attach same credit entitlement (one-time packs ₹49/99/199) |
| Expiry & no rollover | Configure on credit entitlement (e.g. **30 days**, rollover **off**) |
| Ledger debit/credit | `createLedgerEntry` with `idempotency_key` (409 on duplicate) |
| Refunds / disputes | Dodo MoR + `refund.succeeded` webhooks |
| Webhook delivery | Standard Webhooks signature; retry until 200 |

## What this app handles

| Concern | App |
| --- | --- |
| User ↔ `cus_*` mapping | `metadata.user_id` on checkout + `payment.succeeded` webhook |
| Pack catalog (₹49/99/199) | `src/lib/credits/config.ts` → env product IDs |
| AI feature pricing (margin) | `AI_FEATURE_COSTS` — e.g. joke = 2 credits, image = 15 |
| Enforce spend before AI work | `POST /api/credits/consume` debits then generates |
| Failure reversal | Credit ledger entry (`entry_type: credit`) with `reversal-{operationId}` |
| Simulation mode | Local `.data/punchline-db.json` when `DODO_PAYMENTS_API_KEY` is unset |

## Dashboard setup (test mode)

1. **Credits** → Create credit (custom unit `ai_credit`, precision 0, expiry 30 days, rollover off).
2. **Products** (one-time, INR) → ₹49 / ₹99 / ₹199 packs, each attaching credits (50 / 120 / 280).
3. Copy `cde_*` and `pdt_*` into `.env` (see `.env.example`).
4. **Webhooks** → `POST /api/webhooks/dodo` — subscribe to `payment.succeeded`, `credit.*`, `refund.succeeded`.

# Checkout → credits flow

```mermaid
sequenceDiagram
  participant U as User
  participant App as Punchline Lab
  participant Dodo as Dodo Payments
  U->>App: Sign in with Google (Supabase)
  U->>App: Buy pack on /credits
  App->>Dodo: checkoutSessions.create(product_cart, metadata.user_id)
  Dodo-->>App: checkout_url
  App-->>U: Redirect to hosted checkout
  U->>Dodo: Pay (test card)
  Dodo->>App: webhook payment.succeeded
  App->>App: Save cus_* for user_id + invoice row
  Dodo->>Dodo: Grant credits (product entitlement)
  U->>App: /checkout/success sync balance (poll)
  U->>App: POST /api/credits/consume
  App->>Dodo: ledger debit (idempotency_key)
  App-->>U: Joke text + new balance
```

**Never** grant credits in the browser `return_url` alone — fulfill from webhooks and read balance from Dodo.

Post-checkout `/api/credits/claim` only **syncs** balance from Dodo; it does not mint credits locally.

# Next.js 16 + Vercel + Supabase + Dodo + Replicate Micro-SaaS Architecture & AI Prompts

This guide contains the full architecture blueprint and **ready-to-use AI Copy-Paste Prompts** for building future micro-SaaS applications using this exact tech stack.

---

## Architecture Stack Overview

| Layer | Technology | Responsibilities |
| :--- | :--- | :--- |
| **Framework** | Next.js 16 (App Router + Turbopack) | Server Components, Route Handlers, React 19 UI |
| **Hosting & SSL** | Vercel + Custom Subdomain | Global Edge deployment, zero-config SSL for `pricing.indieapps.in` |
| **Authentication** | Supabase Auth (Google OAuth) | Social login, SSR cookies, session callback at `/auth/callback` |
| **Payments & Ledger** | Dodo Payments | Credit packs (INR/USD), Webhook verification, customer entitlement tracking |
| **AI Inference** | Replicate API (`meta/meta-llama-3-70b-instruct`) | Pay-per-generation LLM output with credit reversal fallback |

---

## Copy-Paste Prompts for Future AI Projects

### Prompt 1: Project Setup & Core Stack
```text
I am building a Next.js 16 (App Router) micro-SaaS application deployed on Vercel with a custom domain.
Tech stack required:
- TailwindCSS & Radix / Shadcn UI components.
- Supabase SSR Auth with Google Social Login (@supabase/supabase-js @supabase/ssr).
- Dodo Payments prepaid credit system with webhooks for fulfillment.
- Replicate API (Meta Llama 3 70B Instruct) for AI feature generation.

Please set up the clean file structure:
1. src/lib/supabase/client.ts & server.ts for browser & SSR auth.
2. src/app/auth/callback/route.ts for OAuth code exchange.
3. src/lib/dodo/client.ts & src/app/api/webhooks/dodo/route.ts for verified payment webhooks.
4. src/lib/credits/ledger.ts & src/app/api/credits/consume/route.ts for credit debiting.
```

### Prompt 2: Dodo Payments Checkout & Webhook Integration
```text
Implement Dodo Payments checkout and webhook processing:
1. Create POST /api/dodo/checkout that accepts packId, reads product ID from env, creates checkoutSession with return_url: "${process.env.NEXT_PUBLIC_APP_URL}/checkout/success?pack=${pack.id}".
2. Create POST /api/webhooks/dodo using 'standardwebhooks' to unwrap webhook-id, webhook-signature, and webhook-timestamp.
3. Listen for 'payment.succeeded' and 'credit.added' events and update user credit entitlement idempotently.
```

### Prompt 3: Replicate AI Generation with Credit Reversal
```text
Implement an AI generation route POST /api/credits/consume:
1. Authenticate user session.
2. Debit feature credit cost from user balance via credit ledger.
3. Call Replicate API (meta/meta-llama-3-70b-instruct) using process.env.REPLICATE_API_TOKEN.
4. If Replicate generation succeeds, return { ok: true, result, balance }.
5. If generation fails, perform an automatic credit reversal and return error response.
```

---

## Quick Command Cheatsheet for Deployment

```bash
# Push environment variables to Vercel production
echo "https://pricing.indieapps.in" | npx vercel env add NEXT_PUBLIC_APP_URL production
echo "https://your-project.supabase.co" | npx vercel env add NEXT_PUBLIC_SUPABASE_URL production
echo "your-supabase-anon-key" | npx vercel env add NEXT_PUBLIC_SUPABASE_ANON_KEY production
echo "r8_your_replicate_token" | npx vercel env add REPLICATE_API_TOKEN production

# Deploy to Vercel Production
npx vercel --prod
```