Data model

Overview

The canonical schema lives in prisma/schema.prisma. IDs are UUIDs (or cuid for some newer models) created by the database.

Hierarchy

Tenant (property management org)
 ├── Property (site / building)
 │    ├── Unit (apartment or suite)
 │    │    ├── VirtualNumber (E.164, telephonyProvider)
 │    │    ├── Call → Approval(s)
 │    │    ├── GuestPass (when enabled)
 │    │    └── Residents (User, many-to-many)
 │    ├── GuestPassPolicy
 │    └── AccessPoint (gate hardware)
 ├── User (admins, PMs, staff, residents)
 │    └── Device (push tokens, platform)
 ├── Invite (resident onboarding)
 ├── ImportBatch (CSV / CSVBox imports)
 └── Subscription / billing (Stripe fields on Tenant)

In product language, a Tenant is often called an organization or management company.

Entities (selected)

Model	Purpose
Tenant	Top-level B2B customer; owns properties, users, entitlements JSON, Stripe customer, plan tier fields.
Property	Physical site; timezone default `America/New_York`; optional `telephonyProviderOverride`.
Unit	Leasable unit; `unitLabel` is the human-visible identifier (not `number` / `name`).
VirtualNumber	Carrier number in E.164 (`e164`); `telephonyProvider` (`twilio` \| `telnyx`); optional quarantineUntil for pool hygiene.
User	Single `name` field; roles include `admin`, `property_manager`, `staff`, `resident`. Links to WorkOS, Clerk where applicable.
Device	Mobile installation; use `isEnabled` (not `enabled`).
Call	Voice session; `startedAt`, `durationSec`, `finalState`.
Approval	Resident decision; `action` is `approve` or `deny`.
Invite	Resident onboarding token tied to a unit; status `PENDING` \| `ACCEPTED` \| `EXPIRED`.
ImportBatch	Bulk import job (`csvbox`, `csv`, `api`); dry-run preview → commit → optional rollback.
GuestPass	Time-bound visitor access with PIN or link; gated by property GuestPassPolicy.
SubscriptionUsageLog	Metered billing usage events for Stripe.

Plan tier vs entitlements

Tenant.planTier / Clerk org publicMetadata.plan_tier: Core, Standard, Pro, Trial (ADR-005).
Tenant.entitlements: JSON module flags (guest passes, delivery scan, etc.). null means all modules enabled for backward compatibility.

See repo runbook docs/TENANT_ENTITLEMENTS.md for the current key set.