backend-patterns

# Backend Patterns Skill **Degree of freedom: MIXED.** Which pattern to apply `[HIGH freedom]`; existing-architecture probes and the validation list `[LOW freedom — run exactly]`. ## This skill vs neighbors | Skill | Owns | |---|---| | **backend-patterns** (this) | Apply queues, caching, rate limits, and serverless/edge patterns | | `audit-backend-architecture` | Read-only architecture audit and pattern advisor: which pattern to pick | ## How to reason 1. **Observe** — existing server/api/actions, ORM, queues, cache 2. **Interpret** — missing pattern vs duplicate vs wrong layer 3. **Classify** — reuse / add-queue / add-cache / add-rate-limit / edge-fn 4. **Severity** — unauthenticated mutation outranks a missing cache ## Worked example > **Observe:** `createOrder` sends email inline; no Inngest/queue; checkout p95 4s. > **Interpret:** confirmation is post-response work, not request-path. > **Classify:** `after()` or an `order/created` job; keep the write transactional. > **Verify:** order row commits; email/inventory run after response; retries do not double-charge. ## Self-critique before reporting - **Existing first** — searched server/api/actions before adding a second pattern - **Auth + validate** — every mutation checks session and Zod - **Idempotent** — retries on the new path do not double-apply - **Right owner** — which architecture to pick → `audit-backend-architecture` Design scalable, maintainable backend architectures using modern patterns and best practices. > Code examples lean on **Next.js App Router + Supabase/Prisma**. The patterns are > stack-agnostic — adapt ORMs, client libraries, and deploy targets to your detected > ecosystem. ## Check existing first [LOW freedom — run exactly] **Before implementing ANY backend pattern, verify:** 1. **Check existing architecture:** ```bash ls -la src/server/ src/api/ app/api/ supabase/functions/ 2>/dev/null cat package.json | grep -i "prisma\|drizzle\|supabase\|trpc" ``` 2. **Check existing patterns:** ```bash rg "createTRPCRouter|publicProcedure" --type ts -l rg "'use server'" --type ts -l ls -la supabase/migrations/*.sql 2>/dev/null | tail -5 ``` 3. **Check database setup:** ```bash cat prisma/schema.prisma 2>/dev/null | head -50 cat supabase/config.toml 2>/dev/null ``` **Why:** Backend changes have wide impact. Understand existing architecture first. ## Server Actions (Next.js 16+) [HIGH freedom] Next.js 16: Turbopack default; `'use cache'` + `cacheComponents`; `reactCompiler: true`; `middleware.ts` → `proxy.ts` (grep both). Instant navigations → `enhance-web-instant-nav`. - Order inside every action: auth check → Zod `safeParse` → execute → map known errors (Prisma `P2002`) → generic failure message. - Return `ActionResult<T>`: `{ success: true, data }` or `{ success: false, error, fieldErrors? }`; never throw to the client. - `revalidatePath` after a successful write. - Post-response work (confirmation email, inventory, notifications) goes in `after()` from `next/server`, keeping the write transactional. ```tsx 'use server' import { after } from 'next/server' export async function createOrder(formData: FormData) { const order = await db.order.create({ data: { /* ... */ } }) after(async () => { // runs after the response is sent await sendOrderConfirmation(order.id) await updateInventory(order.items) }) revalidatePath('/orders') return { success: true, data: order } } ``` Full `createUser` action and the `after()` example: [references/request-patterns.md](references/request-patterns.md) §Server Actions. ## tRPC Setup [HIGH freedom] - `publicProcedure` for reads anyone may do; `protectedProcedure` for anything that uses `ctx.session`. - Every procedure has a Zod `.input()`; mutations stamp `createdById` from the session, not the input. - List endpoints paginate by cursor: fetch `limit + 1`, pop the extra row as `nextCursor`. Full `usersRouter` (getById, create, cursor-paginated list): [references/request-patterns.md](references/request-patterns.md) §tRPC router definition. ## Supabase Edge Functions [HIGH freedom] - `Deno.serve`; answer `OPTIONS` with the CORS headers first. - Verify the webhook signature against the raw body before parsing JSON; `401` on mismatch. - Admin client from `SUPABASE_SERVICE_ROLE_KEY` bypasses RLS; use it only inside the function. - Catch everything; log server-side, return a generic `500` JSON body with CORS headers. Full `process-webhook` function: [references/request-patterns.md](references/request-patterns.md) §Supabase Edge Function. ## Database Patterns [HIGH freedom] - **Optimistic locking** — `version INT` column; `UPDATE ... WHERE id = $1 AND version = $2` and treat 0 rows as a concurrent update. - **Soft deletes** — nullable `deletedAt` with an index; every read filters `deletedAt: null`; delete sets the timestamp. - **Audit logging** — `audit_logs(table_name, record_id, action, old_data, new_data, user_id)` filled by a `SECURITY DEFINER` trigger using `TG_OP`, `row_to_json`, `auth.uid()`. ```sql UPDATE orders SET status = 'shipped', version = version + 1 WHERE id = $1 AND version = $2; -- 0 rows → concurrent update, retry or surface conflict ``` Soft-delete Prisma model and the full audit trigger: [references/data-and-jobs.md](references/data-and-jobs.md) §Soft deletes, §Audit logging. ## Caching Patterns [HIGH freedom] - Next.js: `fetch(url, { next: { revalidate, tags } })`; `revalidateTag` on demand; `unstable_cache` around DB queries with tags. - Redis (Upstash): one `getCachedData(key, fetcher, ttl)` helper, cache-aside; key by entity and id (`user:${id}`). - Pick TTL by staleness tolerance, and always tag so a write can bust the cache. ```tsx const getCachedUser = unstable_cache( async (id: string) => db.user.findUnique({ where: { id } }), ['user'], { revalidate: 3600, tags: ['users'] } ) ``` Next.js cache calls and the Redis helper: [references/data-and-jobs.md](references/data-and-jobs.md) §Next.js cache, §Redis caching. ## Background Jobs [HIGH freedom] - Default: **Inngest**. `inngest.createFunction({ id }, { event }, async ({ event, step }) => ...)`; each side effect in its own `step.run` so retries resume, not restart. - Trigger with `inngest.send({ name: 'order/created', data })` from the Server Action after the write commits. - Early exit (out of stock) is a `step.run` + `return { status: 'cancelled' }`, not a throw. ```tsx export const processOrder = inngest.createFunction( { id: 'process-order' }, { event: 'order/created' }, async ({ event, step }) => { const payment = await step.run('charge-payment', () => chargeCustomer(event.data.paymentMethod)) await step.run('send-confirmation', () => sendOrderConfirmation(event.data.orderId)) return { status: 'completed', paymentId: payment.id } } ) ``` Full Inngest function and the Trigger.dev scheduled-task alternative: [references/data-and-jobs.md](references/data-and-jobs.md) §Background jobs, §Alternatives. ## Rate Limiting [HIGH freedom] - `@upstash/ratelimit` with `Ratelimit.slidingWindow(10, '10 s')` over `Redis.fromEnv()`. - Key by user id (or IP for anonymous); on `!success` return `Too many requests` with `retryAfter` seconds from `reset`. Full `rateLimitedAction`: [references/request-patterns.md](references/request-patterns.md) §Rate limiting. ## Architecture patterns (distributed systems) [HIGH freedom] Gateway, BFF, bulkhead, circuit breaker, outbox+CDC, saga, hexagonal, ACL, and strangler-fig → [references/architecture-patterns.md](references/architecture-patterns.md). Pick the pattern for the topology (no mesh on a monolith; no CQRS unless reads/writes diverge). Timeouts/retries/idempotency → `audit-resilience`; structural gap report → `audit-backend-architecture`. ## Validation [LOW freedom — do not skip] After implementing backend patterns: 1. **Error handling** → All errors caught, logged, safe response returned 2. **Auth checks** → Every mutation verifies authentication 3. **Input validation** → Zod schema on all inputs 4. **Rate limiting** → Sensitive endpoints protected 5. **Idempotency** → Critical operations handle retries 6. **Logging** → Structured logs without sensitive data 7. **Testing** → Unit tests for business logic, integration for APIs