Opinionated conventions for designing, evolving and operating GraphQL APIs.
# GraphQL API taste of a platform engineer - Design the schema around client use cases and domain language, not around database tables. Confidence: 0.90 - Generate types for both server and client from the schema (GraphQL Code Generator or equivalent); never hand-write response types. Confidence: 0.90 - Make fields non-null by default only when the server can always resolve them; keep fields that depend on other services nullable so one failure does not null out the whole response. Confidence: 0.80 - Use one input object per mutation (createOrder(input: CreateOrderInput!)) and return a payload type, not the bare entity. Confidence: 0.85 - Return expected business errors as typed union members in the payload (e.g. OrderCreated | InsufficientStock); reserve the top-level errors array for unexpected failures. Confidence: 0.75 - Paginate lists with Relay-style cursor connections (edges, node, pageInfo) and cap first/last at a sane maximum. Confidence: 0.80 - Batch and cache data loading per request with DataLoader to kill N+1 queries. Confidence: 0.95 - Enforce query depth and complexity limits at the gateway. Confidence: 0.90 - Use persisted queries (allowlisted operation hashes) for first-party clients in production. Confidence: 0.80 - Disable introspection on public production endpoints unless the API is meant to be public. Confidence: 0.70 - Evolve the schema additively and mark old fields with @deprecated(reason: ...); never version the endpoint with /v2. Confidence: 0.90 - Remove a deprecated field only after field-usage metrics show no traffic for a full release cycle. Confidence: 0.85 - Run schema diff checks in CI and fail the build on breaking changes. Confidence: 0.90 - Use globally unique opaque IDs and implement the Node interface for refetching. Confidence: 0.70 - Keep resolvers thin: they call domain services, and authorization lives in that service layer, not in resolver if-statements. Confidence: 0.85 - Name operations in every client query so traces, logs and metrics are readable. Confidence: 0.90 - Colocate fragments with the UI components that use them. Confidence: 0.80 - Prefer custom scalars (DateTime, URL, Email) with validation over plain String. Confidence: 0.75 - Use subscriptions only for genuinely real-time data; polling is fine for anything that changes every few minutes. Confidence: 0.70 - Reach for federation only when several teams own separate subgraphs; one team means one schema. Confidence: 0.75 - Trace every resolver with OpenTelemetry and alert on slow fields, not just slow requests. Confidence: 0.80 - Document every type and field with schema descriptions; the schema is the API reference. Confidence: 0.85
Opinionated conventions for using Redis as a cache: keys, TTLs, invalidation and operations.
# Redis Caching taste of a backend engineer - Default to cache-aside: read from Redis, fall back to the source of truth on a miss, then populate the cache. Confidence: 0.90 - Treat the cache as disposable; the system must stay correct (only slower) if Redis is flushed. Confidence: 0.95 - Set a TTL on every cache key; a key without an expiry is a memory leak waiting to happen. Confidence: 0.90 - Add random jitter to TTLs so keys written together do not expire together. Confidence: 0.85 - Namespace keys as service:entity:id:version (e.g. catalog:product:42:v3) and bump the version on breaking format changes. Confidence: 0.85 - Invalidate by deleting the key after a successful write, not by updating the cached value in place. Confidence: 0.80 - Protect hot keys from stampedes with a short lock (SET key value NX PX) or request coalescing. Confidence: 0.80 - Cache negative results (not found) with a short TTL to absorb lookups for missing ids. Confidence: 0.70 - Store compact serialized values (JSON for debuggability, MessagePack when size matters) and keep values under about 100 KB. Confidence: 0.75 - Use hashes for objects whose fields are read separately, and plain strings for values read whole. Confidence: 0.70 - Never run KEYS in production; use SCAN with a cursor. Confidence: 0.95 - Avoid big keys and huge collections; split anything that would make a single command block for milliseconds. Confidence: 0.85 - Use pipelining or MGET for batch reads instead of one round trip per key. Confidence: 0.85 - Put multi-step atomic logic in a Lua script or a function, not in client-side check-then-set. Confidence: 0.80 - Set maxmemory with an explicit eviction policy (allkeys-lru for pure caches, noeviction for data you must not lose). Confidence: 0.90 - Keep caches and durable data (queues, rate limits, sessions) in separate Redis instances with separate policies. Confidence: 0.80 - Use Redis Streams or a real broker for jobs; plain lists lose work when a consumer crashes. Confidence: 0.70 - Implement rate limiting with a sliding window or token bucket script, not with ad-hoc INCR plus EXPIRE races. Confidence: 0.75 - Set client timeouts and a circuit breaker so a slow Redis degrades to cache misses instead of taking the service down. Confidence: 0.90 - Monitor hit ratio, evictions, memory fragmentation and latency, and alert on a falling hit ratio. Confidence: 0.85 - Require auth and TLS, disable or rename dangerous commands (FLUSHALL, CONFIG), and never expose Redis to the internet. Confidence: 0.95 - Do not cache what is already fast; measure the source latency before adding a cache layer. Confidence: 0.80
Opinionated preferences for building accessible web interfaces that work for keyboard and screen reader users.
# Web Accessibility taste of a frontend engineer - Use semantic HTML first (button, a, nav, main, label); add ARIA only when no native element fits. Confidence: 0.95 - Never put click handlers on div or span; if it acts like a button, it is a button. Confidence: 0.95 - Links navigate and buttons perform actions; do not swap them for styling reasons. Confidence: 0.90 - Every form input has a visible, programmatically associated label; placeholders are not labels. Confidence: 0.95 - Keep one h1 per page and never skip heading levels for visual size; style with CSS instead. Confidence: 0.80 - Write alt text that describes the purpose of the image, and use alt="" for purely decorative images. Confidence: 0.90 - Keep a visible focus indicator on every interactive element; use :focus-visible rather than removing outlines. Confidence: 0.95 - Every feature must work with the keyboard alone, in a logical tab order, with no keyboard traps. Confidence: 0.95 - Avoid positive tabindex values; fix the DOM order instead. Confidence: 0.90 - Meet WCAG AA contrast: 4.5:1 for body text and 3:1 for large text and UI components. Confidence: 0.90 - Never convey meaning by color alone; pair it with text, an icon or a pattern. Confidence: 0.90 - Use the native dialog element (or a well-tested library) for modals, trap focus while open and return focus to the trigger on close. Confidence: 0.85 - Announce async status and errors with an aria-live region or role="alert", and move focus to the error summary after a failed submit. Confidence: 0.80 - Honor prefers-reduced-motion and avoid autoplaying motion longer than five seconds. Confidence: 0.85 - Make touch targets at least 24x24 CSS pixels, ideally 44x44. Confidence: 0.75 - Size text in rem and make sure the layout survives 200% zoom and 320px width without horizontal scrolling. Confidence: 0.85 - Add a "Skip to main content" link as the first focusable element. Confidence: 0.80 - Set the lang attribute on html and on any inline passage in another language. Confidence: 0.85 - Run axe or Lighthouse checks in CI, knowing they catch only about a third of issues. Confidence: 0.85 - Test critical flows manually with a screen reader (VoiceOver and NVDA) before each major release. Confidence: 0.80 - Lint JSX with eslint-plugin-jsx-a11y and treat its errors as build failures. Confidence: 0.75 - Prefer accessible component primitives (Radix, React Aria) over building comboboxes and menus from scratch. Confidence: 0.80