Backend Toolkit

Choose the API protocol (REST / GraphQL / gRPC) by traffic shape and design resources, versioning, and async patterns. Use when adding a new API surface, designing a service boundary, or when clients complain about over/under-fetching. Not for the schema/error envelope details (use api-contract) or per-resource access control (use authorization).

Define a schema-first API contract — standardized error envelope (RFC 9457), pagination, status codes, consistent JSON shapes. Use when establishing API conventions, before multiple teams consume an API, or when error responses are inconsistent. Not for choosing the protocol or modeling resources (use api-design) or for runtime input parsing at the boundary (use data-validation).

Design access control — RBAC for coarse function-level checks, Postgres Row Level Security (RLS) for row-level data isolation, ABAC pushed to the app/policy layer. Use when adding permissions, building multi-user data access, or when one user can see another's data. Not for establishing who the caller is (use authentication) or tenant isolation specifically (use multitenancy-audit).

Build a backend CI/CD pipeline — containerized builds, type-check/lint/test gates, DB migration as an explicit gate, SHA-tagged images, and blue-green/canary deploy with rollback. Use at project init, when deploys are manual/risky, or when migrations break production. Not for designing the migration itself (use migration-strategy) or the test pyramid (use test-strategy).

Design a relational schema — normalize to 3NF then denormalize with justification, choose the right Postgres index type per data shape, enforce constraints at the DB. Use when modeling a new domain, when queries are slow, or before a migration. Not for diagnosing slow queries (use query-optimization) or shipping the change without downtime (use migration-strategy).

Backend testing pyramid — unit for pure logic, integration against a real DB (Testcontainers), and consumer-driven contract testing (Pact) for service boundaries. Use before a feature, after a bug fix, or when services break each other on deploy. Not for load testing (use performance-profiling) or security testing (use backend-security-audit).

Build LLM features on the backend — deterministic agent loops (round-trip every tool call by id), RAG over a vector store, token/cost accounting, streaming, eval harness, and prompt-injection defense (treat all model context as untrusted). Use when adding an AI feature, building RAG, or wiring an agent loop. Not for the AI streaming UI on the frontend (use frontend-toolkit's AI integration) or general boundary input parsing (use data-validation).

Choose and implement auth correctly — JWT vs session vs OAuth decision, pin allowed algorithms server-side, rotate refresh tokens with reuse detection, avoid the classic JWT pitfalls. Use when adding login, integrating OAuth, or when token handling looks risky. Not for access control / permissions (use authorization) or a broader OWASP audit (use backend-security-audit).

Design webhooks correctly on both sides — sending (HMAC signing, retries with backoff, at-least-once) and receiving (verify signature on raw body, enqueue + 200 fast, dedupe on event id). Use when adding webhook delivery or consuming a provider's webhooks. Not for internal service-to-service events (use async-messaging) or general outbound-call retry policy (use resilience-patterns).

Build reliable event-driven flows with the Transactional Outbox pattern — write state and event in one transaction, relay asynchronously, achieve at-least-once delivery + consumer idempotency. Use when an action must reliably trigger downstream work, or when events are lost on crash (dual-write problem). Not for simple background work without state+event reliability (use background-jobs) or outbound HTTP webhook specifics (use webhook-design).

Run work off the request thread reliably — queue design, retries with exponential backoff + jitter, dead-letter queues, concurrency control, and idempotent handlers. Use when an operation is slow/external, when jobs fail silently, or when retries cause duplicates. Not for write+event transactional reliability — the dual-write problem (use async-messaging Outbox) or webhook-receiver specifics (use webhook-design).

Validate untrusted input once at the trust boundary and return a typed parsed value (parse, don't validate). Use when adding an endpoint, accepting external input, or when invalid data leaks past the boundary into business logic. Not for defining the API contract/schema itself (use api-contract) or downstream business-rule logic — parse only at the trust boundary.

Design a cache layer — cache-aside read/write/invalidate, TTL + jitter, stampede prevention (single-flight / probabilistic refresh), and explicit invalidation. Use when read latency is high, the DB is read-bound, or a hot key causes thundering-herd load. Not for fixing the slow query at its source (use query-optimization first) or HTTP/browser caching (a frontend concern).

Ship schema changes with zero downtime using the expand-contract pattern — never rename/drop in one step, backfill safely, keep old and new code coexisting during deploy. Use before any schema change on a live database. Not for designing the schema (use schema-design) or wiring migrations into CI (use cicd-pipeline).

Choose a tenant isolation strategy (shared-schema+RLS / schema-per-tenant / db-per-tenant), propagate tenant context reliably per request, and keep an append-only audit log. Use when building multi-tenant SaaS, when tenants could see each other's data, or when compliance needs an audit trail. Not for per-user (non-tenant) access control (use authorization) or general OWASP review (use backend-security-audit).

Find and fix slow Postgres queries — rank by pg_stat_statements, diagnose with EXPLAIN (ANALYZE, BUFFERS), kill N+1 at the ORM layer, add the right index. Use when an endpoint is slow, DB CPU is high, or before scaling traffic. Not for schema/index design from scratch (use schema-design) or result-level caching (use caching-strategy).

Instrument a backend with the three signals unified by one correlation context — structured logs, metrics (RED for services, USE for resources), and distributed tracing (OpenTelemetry + W3C Trace Context). Use before production, when debugging is blind, or when an incident has no trail. Not for diagnosing specific bottlenecks (use performance-profiling) or AI-specific token/cost metrics (use ai-llm-backend on top of this backbone).

Apply reliability primitives — capped exponential backoff with jitter, circuit breakers, timeouts, and idempotency keys — to every outbound call and mutating endpoint. Use when integrating an external service, when retries cause duplicate effects, or before shipping a payment/order flow. Not for job-runner retry config specifically (use background-jobs) or webhook-delivery specifics (use webhook-design, which reuses these primitives).

Find and fix backend bottlenecks — connection pooling, p95/p99 latency, load testing with SLO-aligned thresholds (k6), and CPU profiling (flame graphs). Use when latency is high, throughput plateaus, or before scaling traffic. Not for DB query specifics (use query-optimization) or read-load shedding (use caching-strategy).

Audit a backend against the OWASP API Security Top 10 — BOLA/BFLA, injection, secrets, mass assignment — with an exploit scenario per finding. Use when adding auth/external input, before shipping, or on a quarterly security review. Not for implementing auth from scratch (use authentication / authorization) — each finding maps to its sibling skill for the fix.

Use transactions and isolation levels correctly — keep them short, no network calls inside, explicit isolation, retry on serialization conflicts, and choose optimistic vs pessimistic locking. Use when a write spans multiple tables, when concurrent updates corrupt data, or when designing money/inventory flows. Not for cross-service event delivery (use async-messaging Outbox) or schema-level constraints (use schema-design).

Default to a modular monolith with enforced internal boundaries; treat microservices as a destination after boundaries prove stable, not a starting point. Use when structuring a backend, when tempted to split into services, or when module boundaries blur. Not for the actual schema-split / service-extraction migrations (use migration-strategy + schema-design).