backend-dev-guidelines

Backend development guide for Langfuse's monorepo using tRPC, Next.js, BullMQ, and TypeScript.

• Comprehensive backend best practices for Langfuse's stack
• Guides tRPC, API endpoints, queues, services, and DB access
• Enforces layered architecture and multi-tenant isolation
• Covers observability, validation, and testing patterns

• Layered architecture: tRPC → services → DB (web), queue → services → DB (worker)
• Dual DB system: PostgreSQL (core) + ClickHouse (analytics)
• ProjectId filtering for multi-tenant isolation
• Zod v4 for input validation
• OpenTelemetry instrumentation (first import)
• traceException for error handling
• env.mjs for environment configuration
• Jest (web) and vitest (worker) for testing

1. 1.Create tRPC router in features/[feature]/server/*Router.ts
2. 2.Use protected/public procedures with auth and entitlement checks
3. 3.Register queue processors in WorkerManager in app.ts
4. 4.Validate inputs with Zod v4 schemas
5. 5.Handle errors with traceException
6. 6.Test with Jest (web) or vitest (worker)