Comprehensive backend development guide for Langfuse's Next.js 14/tRPC/Express/TypeScript monorepo. Use when creating tRPC routers, public API endpoints, BullMQ queue processors, services, or working with tRPC procedures, Next.js API routes, Prisma database access, ClickHouse analytics queries, Redis queues, OpenTelemetry instrumentation, Zod v4 validation, env.mjs configuration, tenant isolation patterns, or async patterns. Covers layered architecture (tRPC procedures → services, queue processors → services), dual database system (PostgreSQL + ClickHouse), projectId filtering for multi-tenant isolation, traceException error handling, observability patterns, and testing strategies (Jest for web, vitest for worker).
Backend Development Guidelines
Purpose
Establish consistency and best practices across Langfuse's backend packages (web, worker, packages/shared) using Next.js 14, tRPC, BullMQ, and TypeScript patterns.
When to Use This Skill
Automatically activates when working on:
Creating or modifying tRPC routers and procedures
Creating or modifying public API endpoints (REST)
Creating or modifying BullMQ queue consumers and producers
Building services with business logic
Authenticating API requests
Accessing resources based on entitlements
Implementing middleware (tRPC, NextAuth, public API)
Database operations with Prisma (PostgreSQL) or ClickHouse
Observability with OpenTelemetry, DataDog, logger, and traceException
Input validation with Zod v4
Environment configuration from env variables
Backend testing and refactoring
Quick Start
UI: New tRPC Feature Checklist (Web)
Router: Define in features/[feature]/server/*Router.ts
: Use appropriate procedure type (protected, public)
Procedures
Authentication: Use JWT authorization via middlewares.
Entitlement check: Access resources based on resource and role
Validation: Zod v4 schema for input
Service: Business logic in service file
Error handling: Use traceException wrapper
Tests: Unit + integration tests in __tests__/
Config: Access via env.mjs
SDKs: New Public API Endpoint Checklist (Web)
Route file: Create in pages/api/public/
Wrapper: Use withMiddlewares + createAuthedProjectAPIRoute
Types: Define in features/public-api/types/
Authentication: Authorization via basic auth
Validation: Zod schemas for query/body/response
Versioning: Versioning in API path and Zod schemas for query/body/response
Tests: Add end-to-end test in __tests__/async/
New Queue Processor Checklist (Worker)
Processor: Create in worker/src/queues/
Queue types: Create queue types in packages/shared/src/server/queues
Service: Business logic in features/ or worker/src/features/
Error handling: Distinguish between errors which should fail queue processing and errors which should result in a succeeded event.
Queue registration: Add to WorkerManager in app.ts
The shared package provides types, utilities, and server code used by both web and worker packages. It has 5 export paths that control frontend vs backend access:
Reference existing Langfuse features for implementation patterns:
Datasets (web/src/features/datasets/) - Complete feature with tRPC router, public API, and service
Prompts (web/src/features/prompts/) - Feature with versioning and templates
Evaluations (web/src/features/evals/) - Complex feature with worker integration
Public API (web/src/features/public-api/) - Middleware and route patterns
Anti-Patterns to Avoid
❌ Business logic in routes/procedures
❌ Direct process.env usage (always use env.mjs/env.ts)
❌ Missing error handling
❌ No input validation (always use Zod v4)
❌ Missing projectId filter on tenant-scoped queries
❌ console.log instead of logger/traceException (OpenTelemetry)
Service layer overview, dependency injection patterns, singleton patterns, repository pattern for data access, service design principles, caching strategies, testing services
Dual database architecture (PostgreSQL via Prisma + ClickHouse via direct client), PostgreSQL CRUD operations, ClickHouse query patterns (queryClickhouse, queryClickhouseStream, upsertClickhouse), repository pattern for complex queries, tenant isolation with projectId filtering, when to use which database
Environment variable validation with Zod, package-specific configs (web/env.mjs with t3-oss/env-nextjs, worker/env.ts, shared/env.ts), NEXT_PUBLIC_LANGFUSE_CLOUD_REGION usage, LANGFUSE_EE_LICENSE_KEY for enterprise features, best practices for env management
Integration tests (Public API with makeZodVerifiedAPICall), tRPC tests (createInnerTRPCContext, appRouter.createCaller), service-level tests (repository/service functions), worker tests (vitest with streams), test isolation principles, running tests (Jest for web, vitest for worker)
Related Skills
database-verification - Verify column names and schema consistency
skill-developer - Meta-skill for creating and managing skills
