Skip to content

Multi Tenancy and RBAC

Ankit Upadhyay edited this page Jul 24, 2026 · 2 revisions

Multi-Tenancy and RBAC

Every clinic is a tenant, and almost every record is organization-scoped. Getting this boundary right is what keeps one clinic's financial and clinical data invisible to another.

Two tenancy models

Yosemite Crew uses row-level org scoping for the core product and schema-per-tenant for the developer platform.

Row-level org scoping (core product)

  • Core entities carry an organisationId; queries and RBAC checks are scoped by it. Cross-tenant access is a bug class, not a feature — the boundary was hardened repo-wide in PR #1860 (merged 2026-07-18): tenant scope is now derived from the resource being accessed and permission checks were tightened. New cross-tenant findings are treated as security bugs as found.
  • An Organization model holds locale/currency (immutable after onboarding), country/regulatory config, feature flags, and appointment configuration. See the org model in the architecture guide.

Schema-per-tenant (developer platform)

  • packages/database/src/tenant.ts implements schema-per-tenant provisioning: a tenant_<key> Postgres schema per developer tenant plus a public control plane, with per-tenant Prisma client caching.
  • registerTenant() records a region on the control-plane row at provision time — the seam that makes future multi-region an additive change rather than a backfill (ADR-0004).
  • The v1 Developer Data API deliberately does not depend on this machinery yet; it scopes by organisationId rows.

RBAC: seven roles, permission strings

Authorization is role-based and org-scoped. The model has seven roles, each carrying fine-grained permission strings checked per route/action:

Role Typical scope
OWNER Full org control
ADMIN Org administration
SUPERVISOR Oversight across clinical + front desk
VETERINARIAN Clinical: SOAP, prescriptions, vitals, discharge, controlled-substance logging
TECHNICIAN Vitals, tasks, lab orders, SOAP view
ASSISTANT Support tasks
RECEPTIONIST Appointments, check-in, billing/invoices, triage view

Permissions are strings like appointments:view:any, prescription:write, controlled-substances:log, billing:view:any, vitals:record. They travel in the session's org context claim (see Authentication and Identity) and are enforced server-side. This role structure was preserved across the SuperTokens migration.

flowchart LR
    U[User] -->|session| S[OrgSessionClaim<br/>orgId + role + permissions]
    S --> M{requireWebAuth / requireScope}
    M -->|orgId match + permission| OK[Handler runs, scoped to orgId]
    M -->|mismatch| DENY[403]
Loading

Developer API scopes

The developer platform layers a scope model on top: DeveloperApiKeys carry narrow scopes (config:read, config:draft:write, and the canonical :read scopes), enforced by requireScope. The AI editing agent is deliberately capped at config:draft:write and cannot publish — see ADR-0005.

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally