backend-dev-guidelines

name	backend-dev-guidelines
description	Build or review Langfuse backend code. Use for tRPC routers, public REST APIs, BullMQ processors, services, middleware, Prisma or ClickHouse access, OpenTelemetry, Zod, environment configuration, or backend tests.

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

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
New concepts in shared code	You are adding a field, option, flag, or enum member to a shared abstraction	references/new-concepts.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