Backend Dev Guidelines

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 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.

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.
• 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 |

| 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 |