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 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.
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 |
| Architecture and package boundaries |
You need the web/worker/shared split, request flow, or queue lifecycle |
references/architecture-overview.md |
| Routing and controllers |
You are writing tRPC procedures, public API routes, or queue entrypoints |
references/routing-and-controllers.md |
| Middleware and auth |
You are changing request auth, permissions, or middleware composition |
references/middleware-guide.md |
| Services and repositories |
You are placing business logic, repository code, or DI patterns |
references/services-and-repositories.md |
| Database access |
You are touching Prisma, ClickHouse, tenant filters, or query patterns |
references/database-patterns.md |
| New concepts in shared code |
You are adding a field, option, flag, or enum member to a shared abstraction |
references/new-concepts.md |
| Configuration |
You are adding env vars, startup config, or runtime toggles |
references/configuration.md |
| Testing |
You are adding or updating backend tests |
references/testing-guide.md |
1---
2name: backend-dev-guidelines
3description: 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.
4metadata:
5 source: https://skillmd.com/skills/langfuse/backend-dev-guidelines
6---
7
8# Backend Development Guidelines
9
10Use this skill for backend and API work across `web/`, `worker/`, and
11`packages/shared/`.
12
13## When to Apply
14
15- Creating or modifying tRPC routers and procedures
16- Creating or modifying public API endpoints
17- Creating or modifying queue processors, producers, or queue-backed workflows
18- Building or refactoring backend services and repositories
19- Working on backend auth, middleware, validation, or observability
20- Updating Prisma or ClickHouse access patterns
21- Adding a field, option, flag, or enum member to shared backend code
22- Adding or fixing backend tests
23
24## How to Read This Skill
25
26- Use this `SKILL.md` when the task spans multiple backend areas or you need the
27 end-to-end reference map.
28- Read only the specific reference file that matches the work when the scope is
29 narrower.
30- If the task introduces a user-supplied URL, an outbound HTTP request, a new
31 integration, or touches secrets, RBAC, or redirect handling, also load the
32 shared [`security-review`](../security-review/SKILL.md) skill before
33 designing or implementing the change.
34
35## Before Adding a New Concept
36
37Before adding a field to a shared schema or payload, an option or flag on a
38shared signature, an enum member, an env toggle, or a branch that exists for one
39caller — or before concluding that no change is needed — read
40[`references/new-concepts.md`](references/new-concepts.md).
41
42## Quick Start Checklists
43
44### UI: New tRPC Feature
45
46- Define the router in `features/[feature]/server/*Router.ts`.
47- Use the appropriate protected or public procedure.
48- Authenticate with JWT-aware middleware.
49- Check project/resource access and entitlements.
50- Validate input with Zod v4.
51- Put business logic in a service file.
52- Use `traceException` for error handling where relevant.
53- Add unit or integration tests in `__tests__/`.
54- Access config via `env.mjs`.
55
56### Existing Endpoint: Additive Field or Filter
57
58Before coding, classify the change as a new endpoint, an additive field/filter
59on an existing endpoint, or a semantic replacement/breaking change.
60
61For an additive field/filter:
62
63- Reuse the canonical predicate. For endpoints that already support field-group
64 selection, reuse their existing field-group/projection path.
65- Preserve the endpoint's existing response contract: use the normal optional
66 partial-row schema and converter path for field-group endpoints; retain the
67 strict response schema and converter path for ordinary endpoints.
68- Do not create API-version-specific field sets, casts, or "must be selected"
69 runtime assertions unless compatibility requires them.
70- Extend examples and contracts; do not replace an existing filter example.
71- Write one test per unique boundary, not one test per file touched.
72
73### SDKs: New Public API Endpoint
74
75- Create the route in `pages/api/public/`.
76- Wrap it with `withMiddlewares` and `createAuthedProjectAPIRoute`.
77- Define types in `features/public-api/types/`.
78- Authenticate with basic auth.
79- Validate query, body, and response with Zod schemas.
80- Include API versioning in paths and schemas.
81- Update Fern API definitions to match TypeScript types.
82- Add end-to-end tests in `__tests__/async/`.
83
84### Worker: New Queue Processor
85
86- Create the processor in `worker/src/queues/`.
87- Define queue types in `packages/shared/src/server/queues`.
88- Place business logic in `features/` or `worker/src/features/`.
89- Distinguish failed jobs from jobs that should succeed with a recorded error.
90- Register the queue in `WorkerManager` in `app.ts`.
91- Add worker vitest coverage.
92
93## Core Principles
94
95- tRPC procedures, public API routes, and queue processors delegate business
96 logic to services.
97- Access configuration through `env.mjs`; do not read `process.env` directly
98 outside env setup.
99- Validate all external input with Zod v4.
100- Use Prisma directly for simple CRUD and repositories for complex query access.
101- Express new requirements in the vocabulary shared code already has; adding a
102 concept to a shared abstraction is the last resort, not the first.
103- Use OpenTelemetry and DataDog for backend observability.
104- Always filter project-scoped database queries by `projectId`.
105- Keep Fern API definitions in sync with public TypeScript API contracts.
106- Keep backend tests independent and parallel-safe.
107
108## Live Examples
109
110- tRPC router with project auth and Zod input:
111 `web/src/features/events/server/eventsRouter.ts`.
112- Public API route with middleware and typed request/response schemas:
113 `web/src/pages/api/public/datasets/index.ts`.
114- Worker queue processor with typed jobs, logging, and retry behavior:
115 `worker/src/queues/evalQueue.ts`.
116- Tenant filters for Prisma and ClickHouse:
117 `references/database-patterns.md`.
118
119## Naming Conventions
120
121- tRPC routers: `camelCaseRouter.ts`, for example `datasetRouter.ts`.
122- Services: `service.ts` in the feature server directory.
123- Queue processors: `camelCaseQueue.ts`, for example `evalQueue.ts`.
124- Public API routes: kebab-case filenames, for example `dataset-items.ts`.
125
126## Anti-Patterns to Avoid
127
128- Business logic in routes or procedures.
129- Direct `process.env` usage instead of `env.mjs` / `env.ts`.
130- Missing error handling.
131- Missing input validation.
132- Missing `projectId` filters on tenant-scoped queries.
133- `console.log` instead of `logger` / `traceException`.
134
135## Reference Map
136
137| Topic | Read this when | File |
138| ----------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
139| Architecture and package boundaries | You need the web/worker/shared split, request flow, or queue lifecycle | [references/architecture-overview.md](references/architecture-overview.md) |
140| Routing and controllers | You are writing tRPC procedures, public API routes, or queue entrypoints | [references/routing-and-controllers.md](references/routing-and-controllers.md) |
141| Middleware and auth | You are changing request auth, permissions, or middleware composition | [references/middleware-guide.md](references/middleware-guide.md) |
142| Services and repositories | You are placing business logic, repository code, or DI patterns | [references/services-and-repositories.md](references/services-and-repositories.md) |
143| Database access | You are touching Prisma, ClickHouse, tenant filters, or query patterns | [references/database-patterns.md](references/database-patterns.md) |
144| New concepts in shared code | You are adding a field, option, flag, or enum member to a shared abstraction | [references/new-concepts.md](references/new-concepts.md) |
145| Configuration | You are adding env vars, startup config, or runtime toggles | [references/configuration.md](references/configuration.md) |
146| Testing | You are adding or updating backend tests | [references/testing-guide.md](references/testing-guide.md) |