backend-dev-guidelines

name	backend-dev-guidelines
description	Shared backend guide for Langfuse's Next.js/tRPC/BullMQ/TypeScript monorepo — tRPC routers, public REST endpoints, BullMQ processors, services, Prisma/ClickHouse access, Zod validation, and backend tests across web/worker/shared.

Backend Development Guidelines

Backend and API work across web/, worker/, and packages/shared/.

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.

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.

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.
• 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

Topic	Read this when	File
Architecture and package boundaries	You need the web/worker/shared split, request flow, or queue lifecycle	references/architecture-overview.md
Routing and controllers	You are writing tRPC procedures, public API routes, or queue entrypoints	references/routing-and-controllers.md
Middleware and auth	You are changing request auth, permissions, or middleware composition	references/middleware-guide.md
Services and repositories	You are placing business logic, repository code, or DI patterns	references/services-and-repositories.md
Database access	You are touching Prisma, ClickHouse, tenant filters, or query patterns	references/database-patterns.md
Configuration	You are adding env vars, startup config, or runtime toggles	references/configuration.md
Testing	You are adding or updating backend tests	references/testing-guide.md