backend-dev-guidelines

The recommended backend architecture uses a layered design with clear separation of concerns: entry points like tRPC procedures delegate to services, which interact with repositories for data access. This structure enforces consistency across web and worker packages.

To validate inputs in tRPC routers, use Zod v4 input validation across all entry points. This enforces standardized schema validation before requests reach your backend services, ensuring data integrity and consistent API behavior.

Use PostgreSQL for transactional data and ClickHouse for analytics queries. Both database access patterns require tenant isolation via projectId, ensuring multi-tenant data security across all Langfuse backend services and workers.

Yes, OpenTelemetry instrumentation is required. Backend guidelines enforce observability integrations across all tRPC procedures, public API routes, and BullMQ workers to maintain consistent tracing and monitoring standards.

Jest is recommended for testing web packages, while Vitest is used for worker packages. Guidelines specify recommended test placements and isolation practices to maintain reliable, standardized backend testing across the dual-database architecture.

Manage environment configuration by using env.mjs or env.ts files. This standardized config approach ensures all backend packages, including shared modules and BullMQ workers, access environment variables consistently and safely.