Organizations

Every piece of tenant-scoped data in Trovella belongs to an organization. Organizations are the tenancy boundary -- they determine what data a user can see, what actions they can take, and how RLS policies filter every database query.

This topic covers the business logic of organizations: what types exist, how they are created, how membership works, and how the active organization is selected. For how the organization ID flows through the request lifecycle and enforces data isolation, see Identity & Access -- Tenant Isolation.

Core Concepts

Three organization types -- personal, family, and company -- serve different user needs. Every user gets a personal organization on first sign-in. Family and company organizations support collaboration.

Membership links users to organizations with a role (owner, admin, or member). Roles determine what CASL permissions the user has within that organization.

Active organization is a session-level concept. The activeOrganizationId field on the session record determines which organization's data the user is currently working in. All tRPC requests read this field from the server-side session (never from client input) to scope queries.

Pages in This Topic

Page	What It Covers
Organization Types	The three types (personal, family, company), their constraints, and when each applies
Bootstrapping	How a personal organization is created on first sign-in and how the active org is auto-selected
Membership	The member table, roles, the member router (list, update role, remove), and CASL interaction
Active Org Selection	How the session's active organization is set, switched, and consumed by tRPC middleware

Key Code Locations

File	Purpose
packages/auth/src/server.ts	ensurePersonalOrganization, ensureActiveOrganization, Better Auth org plugin config
packages/api/src/routers/organization.ts	Organization detail and update endpoints
packages/api/src/routers/member.ts	Member list, role update, and removal endpoints
packages/api/src/abilities/define-ability.ts	CASL ability definitions per role and org type
packages/db/src/schema/auth.ts	Organization, member, and invitation table definitions
apps/web/src/components/dashboard/dashboard-page.tsx	Server component that calls both bootstrap functions on every page render

Related Topics

• Identity & Access -- Authentication -- how the session (including activeOrganizationId) is created and validated
• Identity & Access -- Authorization -- CASL ability definitions and how roles map to permissions
• Identity & Access -- Tenant Isolation -- how the organization ID drives RLS at the database layer
• Data & Storage -- Schema Design -- organization and member table schemas, tenantPolicies helper
• Data & Storage -- Procedure Chain -- how org context flows through tRPC middleware to create tenant-scoped database transactions
• Application -- Routing & Pages -- the DashboardPage pattern that ensures bootstrapping runs on every authenticated page