backend-dev-guidelines

Backend Development Guidelines

Use this skill for backend and API work across web/, worker/, and packages/shared/.

When to Apply

• Creating or modifying tRPC routers and procedures
• Creating or modifying public API endpoints
• Creating or modifying queue processors, producers, or queue-backed workflows
• Building or refactoring backend services and repositories
• Working on backend auth, middleware, validation, or observability
• Updating Prisma or ClickHouse access patterns
• Adding a field, option, flag, or enum member to shared backend code
• Adding or fixing backend tests

How to Read This Skill

• Use this SKILL.md when the task spans multiple backend areas or you need the end-to-end reference map.
• Read only the specific reference file that matches the work when the scope is narrower.
• If the task introduces a user-supplied URL, an outbound HTTP request, a new integration, or touches secrets, RBAC, or redirect handling, also load the shared security-review skill before designing or implementing the change.

Before Adding a New Concept

Before adding a field to a shared schema or payload, an option or flag on a shared signature, an enum member, an env toggle, or a branch that exists for one caller — or before concluding that no change is needed — read references/new-concepts.md.

Quick Start Checklists

UI: New tRPC Feature

• Define the router in features/[feature]/server/*Router.ts.
• Use the appropriate protected or public procedure.
• Authenticate with JWT-aware middleware.
• Check project/resource access and entitlements.
• Validate input with Zod v4.
• Put business logic in a service file.
• Use traceException for error handling where relevant.
• Add unit or integration tests in __tests__/.
• Access config via env.mjs.

Existing Endpoint: Additive Field or Filter

Before coding, classify the change as a new endpoint, an additive field/filter on an existing endpoint, or a semantic replacement/breaking change.

For an additive field/filter:

• Reuse the canonical predicate. For endpoints that already support field-group selection, reuse their existing field-group/projection path.
• Preserve the endpoint's existing response contract: use the normal optional partial-row schema and converter path for field-group endpoints; retain the strict response schema and converter path for ordinary endpoints.
• Do not create API-version-specific field sets, casts, or "must be selected" runtime assertions unless compatibility requires them.
• Extend examples and contracts; do not replace an existing filter example.
• Write one test per unique boundary, not one test per file touched.

SDKs: New Public API Endpoint

• Create the route in pages/api/public/.
• Wrap it with withMiddlewares and createAuthedProjectAPIRoute.
• Define types in features/public-api/types/.
• Authenticate with basic auth.
• Validate query, body, and response with Zod schemas.
• Include API versioning in paths and schemas.
• Update Fern API definitions to match TypeScript types.
• Add end-to-end tests in __tests__/async/.

Worker: New Queue Processor

• Create the processor in worker/src/queues/.
• Define queue types in packages/shared/src/server/queues.
• Place business logic in features/ or worker/src/features/.
• Distinguish failed jobs from jobs that should succeed with a recorded error.
• Register the queue in WorkerManager in app.ts.
• Add worker vitest coverage.

Core Principles

• tRPC procedures, public API routes, and queue processors delegate business logic to services.
• Access configuration through env.mjs; do not read process.env directly outside env setup.
• Validate all external input with Zod v4.
• Use Prisma directly for simple CRUD and repositories for complex query access.
• Express new requirements in the vocabulary shared code already has; adding a concept to a shared abstraction is the last resort, not the first.
• Use OpenTelemetry and DataDog for backend observability.
• Always filter project-scoped database queries by projectId.
• Keep Fern API definitions in sync with public TypeScript API contracts.
• Keep backend tests independent and parallel-safe.

Live Examples

• tRPC router with project auth and Zod input: web/src/features/events/server/eventsRouter.ts.
• Public API route with middleware and typed request/response schemas: web/src/pages/api/public/datasets/index.ts.
• Worker queue processor with typed jobs, logging, and retry behavior: worker/src/queues/evalQueue.ts.
• Tenant filters for Prisma and ClickHouse: references/database-patterns.md.

Naming Conventions

• tRPC routers: camelCaseRouter.ts, for example datasetRouter.ts.
• Services: service.ts in the feature server directory.
• Queue processors: camelCaseQueue.ts, for example evalQueue.ts.
• Public API routes: kebab-case filenames, for example dataset-items.ts.

Anti-Patterns to Avoid

• Business logic in routes or procedures.
• Direct process.env usage instead of env.mjs / env.ts.
• Missing error handling.
• Missing input validation.
• Missing projectId filters on tenant-scoped queries.
• console.log instead of logger / traceException.

Reference Map