Backend Dev GuidelinesCAUTION

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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`](../security-review/SKILL.md) 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`](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                                                                               |
| ----------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| Arch

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

- Access configuration through `env.mjs`; do not read `process.env` directly

AGENTS.md

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Backend Dev Guidelines](https://modelsatlas.com/skills/langfuse/backend-dev-guidelines/badge.svg)](https://modelsatlas.com/skills/langfuse/backend-dev-guidelines/)

Not your listing, or something out of date? Claim or update your listing.