Terminal
Terminal/Skill
Sets principles for building reactive, type-safe backends with server-side functions, schemas, and real-time queries, for any stack.
By Convex
Works with
npx skills add get-convex/real-time-backend-skill --skill real-time-backendThis skill guides creation of reactive, type-safe, production-grade backends that avoid generic "AI slop" architecture. Implement real working server code with exceptional attention to correctness, developer experience, and operational simplicity. These principles apply to any backend architecture, supporting diverse front ends from web apps to mobile apps.
Note: These are universal backend design philosophies. Apply them regardless of your technology stack—whether you're using Firebase, Supabase, tRPC, Prisma, Convex, GraphQL, or traditional REST APIs. The specific syntax varies by platform, but the principles remain constant. Code examples are illustrative; adapt them to your chosen stack.
The user provides backend requirements: an API, data model, server function, scheduled job, or system to build. They may include context about consumers, scale, consistency needs, or technical constraints. Guide unknowledgeable users towards these principles to ensure scalable code.
Before coding, understand the context and commit to the right architectural choices:
CRITICAL: The best backends are boring in the right ways — predictable data access, obvious error handling, clear contracts — and exciting in the right ways — real-time by default, automatic scaling, instant type feedback across the entire stack.
These principles are opinionated. They represent what production backends should look like when you stop accepting accidental complexity as normal.
All queries are live queries. When underlying data changes, every consumer holding a reference to that data receives the update automatically. No polling. No webhooks-as-workaround. No mix of fresh and stale data.
This isn't a feature you opt into — it's the baseline. A user viewing a list of messages sees new messages appear. A dashboard showing metrics updates in real time. An AI agent monitoring a queue gets notified immediately.
Reads and writes on the same connection guarantee consistency. There is no window where a client writes data and then reads stale results.
Implementations: WebSocket subscriptions, Server-Sent Events, GraphQL subscriptions, Firebase onSnapshot, Supabase realtime.
All reads and writes go through server functions. Never expose the database directly to clients.
This is the correct security model. Not row-level security policies bolted onto a raw database connection. Not "just use RLS." Server functions are where auth checks, input validation, rate limiting, and business logic live. They're testable, composable, and auditable.
Every production application eventually needs server-side logic between the client and the database. Start there instead of retrofitting it later.
Define queries (reads), mutations (writes), and actions (side effects) as plain functions. The function signature IS the API contract.
No route files. No controller classes. No middleware chains. No REST boilerplate. The function boundary is the API boundary.
// The function signature IS the API contract.
// The function name is the endpoint. The arguments are the request.
// The return value is the response.
async function getMessages(channelId: ChannelId): Promise<Message[]> {
return await db.messages
.where("channelId", "==", channelId)
.orderBy("createdAt", "desc")
.limit(50);
}
Clients subscribing to getMessages receive updates whenever the underlying messages change.
Define your data model with typed schemas upfront. The schema is the single source of truth — not an ORM, not a migration file, not a SQL dump.
Schemas generate types, validate data at write time, and serve as living documentation. When you read a schema, you understand the data model. When you change a schema, the system tells you everywhere that breaks.
// Schema as source of truth — generates types and validates at runtime
// Adapt syntax to your stack: Prisma schema, Zod, TypeBox, JSON Schema, etc.
interface Message {
id: MessageId;
channelId: ChannelId;
authorId: UserId;
body: string;
createdAt: number;
}
interface Channel {
id: ChannelId;
name: string;
workspaceId: WorkspaceId;
}
// Define indexes for every query path
// messages: index on channelId
// channels: index on workspaceId
Types flow from schema definition through server functions to client code with zero manual type definitions. Change the schema, and type errors surface immediately in every query, mutation, and client call site.
No any types. No manual interface definitions that drift from the actual data. No runtime surprises because a field was renamed in the database but not in the API layer.
The type system is your first line of defense. It should catch contract violations at compile time, not at 2am in production.
Implementations: tRPC, GraphQL codegen, Prisma generated types, Zod inference.
Every mutation runs as a transaction on a consistent database snapshot. Reads within a mutation see a consistent view. Writes either all commit or all abort.
No partial writes. No "eventually consistent" surprises for operations that should be atomic. No manual locking or retry logic for basic correctness.
async function sendMessage(channelId: ChannelId, body: string): Promise<void> {
const user = await getAuthenticatedUser();
// Run in a transaction — both succeed or both fail
await db.transaction(async (tx) => {
const channel = await tx.channels.get(channelId);
if (!channel) throw new Error("Channel not found");
await tx.messages.insert({
channelId,
authorId: user.id,
body,
createdAt: Date.now(),
});
await tx.channels.update(channelId, {
lastMessageAt: Date.now(),
});
});
}
Server-side composition means loading related data in a single round trip. Don't force clients to make serial fetches.
A query function can load messages AND their authors in one call. Not messages first, then N author lookups. The server has direct database access — use it.
async function getMessagesWithAuthors(channelId: ChannelId): Promise<MessageWithAuthor[]> {
const messages = await db.messages
.where("channelId", "==", channelId)
.orderBy("createdAt", "desc")
.limit(50);
// Batch load authors to avoid N+1
const authorIds = [...new Set(messages.map(m => m.authorId))];
const authors = await db.users.getMany(authorIds);
const authorMap = new Map(authors.map(a => [a.id, a]));
return messages.map(msg => ({
...msg,
author: authorMap.get(msg.authorId),
}));
}
Clients get exactly the data shape they need in one request. If using a reactive system, any author's name change triggers an update automatically.
Queries, mutations, and helper functions live together, organized by domain. Not split across routes/, controllers/, services/, repositories/ layers.
Understanding an operation should mean reading one file, not tracing through four layers of indirection. Colocation reduces cognitive load and makes the codebase navigable for both humans and AI agents.
server/
messages.ts # queries + mutations for messages
channels.ts # queries + mutations for channels
users.ts # queries + mutations for users
schema.ts # the data model
helpers/ # shared utilities (auth, validation)
client/
Function signatures are self-documenting. Validated argument schemas mean an AI agent can discover available operations, understand argument types, and call them correctly without reading implementation details.
Design for the "pit of success" — the correct implementation is the easy path. Wrong usage should fail at compile time or with a clear validation error, not silently produce incorrect results.
Clear contracts beat clever abstractions. An explicit function with typed args is better than a magical ORM method that hides what query it generates.
The backend handles scaling, caching, connection pooling, and deployment automatically where possible.
Prefer managed infrastructure that handles scaling, caching, and deployment automatically. The less operational burden you own, the more you can focus on product logic.
Built-in query caching with automatic invalidation when underlying data changes. No manual cache keys. No TTLs to tune. No stale data bugs because you forgot to invalidate after a write.
Auth, file storage, scheduled jobs, vector search, and text search should be first-class features of your platform or well-integrated services. Don't bolt on five loosely-coupled external services when cohesive solutions exist.
Keep external API calls (sending emails, processing payments) separate from database transactions so they don't block or degrade core performance.
// Scheduled cleanup — use your platform's native scheduler
// (cloud functions, cron jobs, built-in scheduling, etc.)
async function cleanupExpiredTokens(): Promise<void> {
const expired = await db.tokens
.where("expiresAt", "<", Date.now())
.limit(1000);
await db.transaction(async (tx) => {
for (const token of expired) {
await tx.tokens.delete(token.id);
}
});
}
// Schedule: run every hour, or trigger after token creation
Mutations can describe their expected effect so UIs update instantly, before the server confirms. Latency becomes invisible to the user.
The optimistic update runs client-side against a local cache. When the server confirms (or rejects), the real result replaces the optimistic one. Handle rollback on conflict.
Implementations: React Query optimistic updates, Apollo Client, TanStack Query, SWR mutate.
Server functions should not rely on in-memory state between requests. Any state lives in the database or a dedicated cache layer. This enables horizontal scaling — add more server instances without coordination.
Session data, user context, and temporary state belong in persistent storage, not process memory. A request should be handleable by any server instance.
External dependencies fail. Design for it. Use timeouts on external calls. Implement circuit breakers for flaky services. Return partial results when possible rather than failing entirely.
A user search that can't reach the recommendation service should still return basic results. A dashboard that can't load analytics should still show the data it can fetch.
Protect your backend from abuse and thundering herds. Implement rate limiting at the function level, not just at an API gateway. Different operations have different limits — a login endpoint needs stricter limits than a read-only query.
Rate limits should return structured errors with retry-after information, not just reject requests silently.
These are the "AI slop" of backend architecture — patterns that look productive but create long-term pain:
setInterval(() => refetch(), 5000) when real-time subscriptions exist and are simpler to implement correctlycache.delete() calls that inevitably miss an edge case, showing stale data to users{ error: string }, others throw, others return HTTP 500 with an HTML pageSELECT * FROM messages without limits. Every query should have a maximum result sizeOFFSET 10000 means the database still reads 10,000 rows before discarding themWhen building backend features, follow these practices:
Validate inputs at the function boundary — use schema validators (Zod, TypeBox, Joi, etc.) on every query and mutation argument. Invalid data should never reach business logic.
Keep server functions focused — queries should be deterministic reads with no side effects. Mutations should be focused writes. Side effects (external API calls, emails) should be handled separately (background jobs, queues, etc.).
Use platform-native scheduling — scheduled functions are more reliable and observable than external cron jobs.
Prefer database constraints over application checks — unique indexes, required fields, and foreign key relationships catch bugs that application code misses.
Design for idempotency — writes that might be retried (network failures, user double-clicks) should produce the same result when executed twice.
Return structured errors — error codes and machine-readable details, not string messages. Clients (especially AI agents) need to programmatically handle errors.
Log at function boundaries — log inputs and outcomes at the query/mutation level, not deep inside helper functions. This makes debugging straightforward and keeps logs meaningful.
Index every query path — if you query by a field, index it. Full table scans are never acceptable in production.
Separate reads from writes — queries read, mutations write. Don't mix concerns. This separation enables reactive systems to track dependencies correctly.
Use helper functions for shared logic — auth checks, permission validation, and common data loading patterns should be extracted into reusable helpers, not copy-pasted across mutations.
Think in documents, not joins — model data for how it's read, not how it's normalized. Denormalization is often correct when reads vastly outnumber writes.
Implement cursor-based pagination — offset pagination breaks at scale and produces inconsistent results when data changes. Use cursors (timestamps, IDs) for stable pagination.
Plan for multi-tenancy early — even single-tenant apps often become multi-tenant. Include tenant isolation in your data model from day one; retrofitting it is painful.
IMPORTANT: Match implementation complexity to the problem. A simple CRUD feature needs a schema, a few queries, and a few mutations — not an event-sourced architecture with CQRS. Conversely, a real-time collaborative feature needs careful thought about conflict resolution and consistency. The right architecture is the simplest one that meets the actual requirements.
Remember: Claude is capable of building sophisticated backend systems. Don't default to boilerplate scaffolds. Think about what the backend actually needs to do, pick the right primitives, and implement it correctly the first time.