backend-dev-guidelines

This skill acts as a comprehensive technical companion for developers working within the Langfuse monorepo. It enforces strict architectural consistency across web (Next.js 14) and worker (Express) packages, ensuring that backend implementation—from tRPC procedures to complex BullMQ queue processing—adheres to established engineering standards. It is designed for software engineers tasked with building, testing, and maintaining high-performance backend services in a multi-tenant environment. The skill provides clear blueprints for layered architecture, helping developers bridge the gap between HTTP requests, business logic services, and underlying data persistence layers.

• Standardized workflows for creating tRPC routers, protected procedures, and public REST API endpoints with middleware.

• Implementation guides for BullMQ queue consumers, including queue registration, service-level logic, and error handling patterns.

• Database interaction protocols for Prisma (PostgreSQL) and ClickHouse analytics, emphasizing multi-tenant isolation via projectId filtering.

• Observability and reliability frameworks using OpenTelemetry for distributed tracing, DataDog integration, and traceException for structured error management.

• Input validation standards leveraging Zod v4 and environment variable management through env.mjs.

• Testing methodologies for backend components, including unit and integration testing via Jest for web components and Vitest for worker processors.

• Use this skill when scaffolding new features to ensure compliance with architectural layering: API Layer → Service Layer → Database/Queue Layer.

• Refer to the provided checklists for quick validation of authentication, entitlement checks, and middleware implementation when exposing new endpoints.

• Apply traceException wrappers for all asynchronous operations to ensure observability and clean debugging logs.

• Ensure all worker-based background jobs are registered in the WorkerManager and adhere to shared type definitions in packages/shared.

• When implementing multi-tenant features, strictly adhere to the project-based isolation patterns to prevent data leakage between tenants.

• Consult the directory structure reference to place feature-specific logic within the appropriate server or worker package modules.