CRUD Architecture

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.