1---2name: backend3description: Backend — Index4---56# Backend — Index78Persimmon backend features = Server Actions and Route Handlers over Prisma/Postgres, Zod at every boundary, secrets server-side only, persist everything. This mother is a map; follow the child for the actual work.910## Trigger1112- "Receive a webhook" / "verify a Stripe signature"13- "Take payments / issue refunds"14- "Send an email or SMS notification"15- "Build a CRUD admin panel / dashboard"16- "Let the admin edit integration credentials"17- "Add a content/CMS layer with publishing"18- "Stop overselling / double-booking"1920## The child skills2122| Skill | When to use | Owns |23|---|---|---|24| `backend-webhook-handler` | Any inbound webhook | Raw-body signature verify, idempotency, event logging, retry semantics (Route Handler) |25| `backend-stripe` | Payments | Order lifecycle (PENDING → webhook-confirm PAID), PaymentIntent, Stripe.js Elements, refunds, SAQ-A, go-live checklist |26| `backend-notifications` | Email/SMS | One `notify()` over Resend + Twilio, post-commit + graceful degradation, A2P 10DLC trap |27| `backend-admin-panel` | Internal CRUD admin | NextAuth-guarded RSC pages, server-side pagination/search, Server Action CRUD, recharts dashboard |28| `backend-settings-admin` | Editable config/secrets | AES-256-GCM-encrypted `Setting` table, env fallback, per-integration test-connection |29| `backend-content-management` | CMS / editable content | Typed content blocks, sanitize-on-write, media library w/ required alt, slug→301, `revalidateTag` on publish |30| `backend-commerce-concurrency` | Limited inventory/slots | Atomic conditional claims, `FOR UPDATE`, advisory locks, checkout-start holds |31| `backend-account-management` | Real per-person logins + roles (not a shared demo login) | Account/role lifecycle on NextAuth+Prisma: DB-backed auth w/ demo fallback, self-signup → pending → admin role approval, invite links, forgot/set/change password via single-use SHA-256 tokens, admin Accounts panel, the ≥1-admin / promote-not-demote / no-self-lockout invariants |3233## How to route34351. **Money flows** → `backend-stripe` (+ `backend-webhook-handler` for the receiver, + `backend-commerce-concurrency` if inventory is limited).362. **Admin surface** → `backend-admin-panel` (+ `backend-settings-admin` for editable integration config).373. **Editable content** → `backend-content-management`.384. **Outbound comms** → `backend-notifications`.395. **Real user accounts + roles** (signup, invites, password reset, role approval, admin management) → `backend-account-management`. It owns the lifecycle + admin invariants; `backend-admin-panel` renders the panel chrome; `security-nextauth` wires the auth.4041## Persimmon backend defaults — one-screen summary4243- **Zod at every trust boundary** — Server Actions, Route Handlers, webhook payloads, `searchParams`.44- **Webhooks**: `runtime = "nodejs"`, read the **raw body**, verify the signature, dedupe by a unique event id, return 2xx fast.45- **Secrets server-side only** (`import "server-only"`); never `NEXT_PUBLIC_*`.46- **Idempotency** = Prisma unique constraint + `upsert`/`P2002` catch, not application guards alone.47- **Notifications fire post-commit** and must never fail the originating action.48- **Concurrency** uses DB-level guarantees (`$transaction` + `FOR UPDATE` / advisory locks), never read-then-write in app code.49- **Persist every record**; any page reading DB/`auth()` exports `const dynamic = "force-dynamic"`.5051## Anti-patterns banned5253- Parsing a webhook body before verifying its signature, or verifying against a JSON-reserialized body54- Trusting client-sent prices/amounts instead of recomputing server-side55- Letting a failed email/SMS roll back or block the business transaction56- Storing integration secrets in plaintext columns57- Read-then-write inventory checks (the classic oversell race)58- Secrets in client bundles / `NEXT_PUBLIC_*`5960## Relationship to other mothers6162| Mother | Connection |63|---|---|64| `stack` | `stack-server-actions` / `stack-zod-boundary` are the substrate for every child here |65| `data` | `data-prisma-pgvector` owns schema; `data-schema-design` owns modeling rigor; `data-booking-availability` pairs with concurrency |66| `security` | `security-nextauth` guards admin; `security-review` audits the boundaries |67| `infra` | `infra-background-jobs` runs retries/queues; `infra-s3-uploads` backs the media library |68| `frontend` | `backend-admin-panel` composes `frontend-*` children into screens |
Persimmon-Automation-Labs