crud - SKILL.md Agent Skill

name: crud description: Add or modify CRUD entities following the layered architecture pattern with oRPC contracts and Inversify DI. Use when adding new database models, creating API endpoints, or implementing data access layers.

CRUD Architecture

This skill guides implementing CRUD operations following the layered architecture pattern.

Architecture Overview

1. Prisma Schema       → apps/server/src/db/prisma/schema.prisma
2. Zod Types           → packages/common/src/contracts/v1/<entity>/types.ts
3. oRPC Contract       → packages/common/src/contracts/v1/<entity>/router.ts
4. Repository Layer    → apps/server/src/repositories/
5. Controller Layer    → apps/server/src/controllers/
6. oRPC Router (impl)  → apps/server/src/routers/v1/<entity>/router.ts
7. DI Container        → apps/server/src/di/container.ts

Checklist for Adding New CRUD Entity

Add Prisma model in apps/server/src/db/prisma/schema.prisma
Run migration: cd apps/server && bun run db:migrate
Regenerate client: cd apps/server && bun run db:generate
Create Zod types in packages/common/src/contracts/v1/<entity>/types.ts
Create oRPC contract in packages/common/src/contracts/v1/<entity>/router.ts
Export from packages/common/src/contracts/index.ts
Merge into packages/common/src/contracts/app-contract.ts
Create Repository in apps/server/src/repositories/ (with @injectable())
Create Controller in apps/server/src/controllers/ (with @injectable())
Create oRPC router implementation in apps/server/src/routers/v1/<entity>/router.ts
Register handlers in apps/server/src/routers/orpc.ts
Register Repository and Controller bindings in DI container
Run build to verify: cd apps/server && bun run build

Critical Gotchas

1. Clerk Integration

Organization IDs are NOT UUIDs — Clerk uses org_xxxxx format. Use z.string().min(1) not z.string().uuid()
Don't pass organizationId in inputs — Get it from context.orgId in router handlers
Webhooks may not have synced (optional consideration) — Use getOrCreate patterns for users/orgs when webhooks aren't guaranteed

2. Foreign Key Constraints (optional)

If entity has FK to users (e.g., created_by), user must exist first
Use ensureUser and ensureOrganization utilities before creating records
See apps/server/src/utils/ensure-user.ts and ensure-organization.ts

3. oRPC Patterns

Use authed middleware from orpc-middleware.ts for authenticated routes — no manual auth checks
Use unwrapResult(result) to convert Result<T> into a thrown ORPCError on failure
Contracts define HTTP method and path (e.g., method: 'GET', path: '/v1/entities')
Error codes are defined in packages/common/src/contracts/errors.ts via oc.errors()

For detailed implementation patterns, see reference.md.