backend-patterns
Backend entity patterns - services with DI, Drizzle schemas (3-file pattern), ORPC routers, TypeIDs, neverthrow. Use when creating services, schemas, routers, or new entities.
When & Why to Use This Skill
This Claude skill streamlines backend development by enforcing consistent architectural patterns and best practices. It provides a standardized framework for implementing services with Dependency Injection (DI), Drizzle ORM schemas using a specialized 3-file pattern, and type-safe ORPC routers. By integrating robust functional error handling with 'neverthrow' and structured TypeIDs, it ensures high maintainability, type safety, and scalability across complex TypeScript monorepo environments.
Use Cases
- Case 1: Rapidly scaffolding new backend entities by following a step-by-step workflow from TypeID definition to API router export.
- Case 2: Implementing a standardized database layer using Drizzle ORM with separated concerns for schemas, Zod validation, and table relations.
- Case 3: Enhancing backend reliability by replacing traditional try-catch blocks with 'neverthrow' for explicit and type-safe error handling in services.
- Case 4: Setting up a scalable Dependency Injection pattern for services to improve code testability and decouple business logic from external dependencies.
- Case 5: Building type-safe API layers with ORPC that seamlessly map service results to standardized error responses for frontend consumption.
| name | backend-patterns |
|---|---|
| description | Backend entity patterns - services with DI, Drizzle schemas (3-file pattern), ORPC routers, TypeIDs, neverthrow. Use when creating services, schemas, routers, or new entities. |
Backend Patterns
Use this skill when building backend features. Follow these patterns for consistency.
Project Setup
Replace these placeholders for your project:
@project/→ your package scope (e.g.,@myapp/)packages/paths follow standard monorepo layout
Expected packages:
@project/db- Drizzle database client, DB_SCHEMA export@project/shared- TypeIDs, constants, shared schemas@project/logger- Pino logger wrapper
Quick Reference
| Entity Type | Pattern | Files to Create/Modify |
|---|---|---|
| Service | Factory function with deps, neverthrow | packages/api/src/services/xxx-service.ts, context.ts |
| Schema | 3-file pattern | .db.ts, .zod.ts, .relations.ts in packages/db/src/schema/ |
| Router | ORPC procedures, Result→Error mapping | packages/api/src/routers/xxx-router.ts, routers.ts |
| TypeID | Prefixed ID | packages/shared/src/typeid.schema.ts |
Key Conventions
- db.query preferred over db.select for simple lookups (see service.md)
- neverthrow for service error handling,
.match()in routers (see router.md) - Zod enums with
as const+z.enum()pattern (see schema.md)
Pattern Details
- For service creation, see service.md
- For schema creation, see schema.md
- For router creation, see router.md
Workflow: Adding a New Entity
- Add TypeID prefix to
packages/shared/src/typeid.schema.ts - Create schema files in
packages/db/src/schema/{domain}/ - Create service in
packages/api/src/services/ - Add to context in
packages/api/src/context.ts - Create router in
packages/api/src/routers/ - Export router in
packages/api/src/routers/routers.ts - Run
bun run db:generateif schema changed