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 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`](../security-review/SKILL.md) skill before
  designing or implementing the change.

## 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.
- 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](references/architecture-overview.md)         |
| Routing and controllers             | You are writing tRPC procedures, public API routes, or queue entrypoints | [references/routing-and-controllers.md](references/routing-and-controllers.md)     |
| Middleware and auth                 | You are changing request auth, permissions, or middleware composition    | [references/middleware-guide.md](references/middleware-guide.md)                   |
| Services and repositories           | You are placing business logic, repository code, or DI patterns          | [references/services-and-repositories.md](references/services-and-repositories.md) |
| Database access                     | You are touching Prisma, ClickHouse, tenant filters, or query patterns   | [references/database-patterns.md](references/database-patterns.md)                 |
| Configuration                       | You are adding env vars, startup config, or runtime toggles              | [references/configuration.md](references/configuration.md)                         |
| Testing                             | You are adding or updating backend tests                                 | [references/testing-guide.md](references/testing-guide.md)                         |