prisma-schema-conventions

Prisma schema conventions

Modeling decisions locked in by production experience. They apply to every new entity unless an explicit, recorded decision says otherwise.

1. Multi-tenancy: workspaceId on every entity

Every business entity carries a workspaceId (row-level isolation, single database). Isolation is enforced at the data layer — every query filters by workspace — and the id always comes from the authenticated context, never from client input.

model Task {
  id          String   @id @default(uuid())
  workspaceId String
  workspace   Workspace @relation(fields: [workspaceId], references: [id])
  // ...
  @@index([workspaceId])
}

Watch out: confirm early with the architect whether the project is actually multi-tenant. A mismatch between the data model document (single-tenant) and the commercial document (multi-tenant) is a classic error — resolve it BEFORE the first production migration, not after.

2. Criticality / priority: numeric scale, never boolean

criticality Int (e.g. 1–5). A boolean ("critical yes/no") doesn't survive the first meeting where the client asks for "medium priority". If the model document shows boolean on one entity and integer on another, treat it as an inconsistency to resolve — model as Int and flag it.

3. Idempotent recurrence

Recurring tasks/events are generated from a template, with a composite unique key (templateId + target date):

model Task {
  // ...
  templateId String?
  targetDate DateTime?
  @@unique([templateId, targetDate])
}

The recurrence generator can run any number of times (duplicated cron, retry, reprocessing) without creating duplicates. Idempotency by design, not by application logic.

4. Documents versioned by lineage

Never overwrite a file. Each version is a new row, grouped by a lineage id:

model Document {
  id        String  @id @default(uuid())
  lineageId String              // groups all versions of the "same" document
  version   Int
  active    Boolean @default(true) // only one active version per lineage
  // ...
  @@unique([lineageId, version])
}