drive/dev/docs/models.md

Data models (users, orgs, accounts, drives)

This doc describes the current model for identity, org membership, and storage tenancy.

Core ideas

• Account is a principal (a user’s identity within an org), not a storage tenant.
• Drive is the storage tenant (the partition key for VFS + blobs).
• VFS authorization separates:
  • tenant: which drive is being accessed, and
  • actor: who is performing the action.

Entities

User

Authenticated human identity.

Organization

Top-level container for org-owned resources:

• billing, policies, API keys, integrations, audit log, etc (all keyed by org_id)

Account (principal)

Represents a user’s identity within an org (membership).

Fields:

• org_id, user_id
• role (org-level role), status (invited/active/removed/etc)
• timestamps

Invariant:

• UNIQUE(org_id, user_id) (one account per user per org)

Drive (storage tenant)

Storage container that owns the filesystem.

Fields:

• org_id
• optional owner_account_id (for “personal drive inside this org”)
• quota/usage metadata (quotas are per-drive)
• timestamps

Invariants:

• Personal drive: UNIQUE(org_id, owner_account_id) (one personal drive per account per org).
• Shared/org drive: owner_account_id IS NULL.

Relationships

users 1 ── * accounts * ── 1 organizations
organizations 1 ── * drives 1 ── * vfs_nodes

Interpretation:

• A user can be in many orgs (via many accounts).
• An org can have many members (many accounts).
• Storage is owned by drives (org-scoped), not by accounts.

VFS tenancy + scope

Scope should carry the VFS tenant key and actor identity separately:

• Scope.DriveID = the storage tenant partition key (used to constrain all VFS reads/writes).
• Scope.RootNodeID + Scope.AllowedNodes = the accessible boundary within that drive.
• Scope.ActorKind + Scope.ActorID = who performs the action (authenticated account vs share link).

Sharing model

Separate “where the shared content lives” from “who created/manages the share record”.

Shape:

node_shares.drive_id                = storage tenant containing the shared nodes
node_shares.created_by_account_id   = principal that created the share

share_permissions.account_id        = principal allowed (NULL = public)

Consumption semantics:

• Scope.DriveID comes from node_shares.drive_id (tenant).
• Scope.Actor… comes from either the share link (public) or the consuming principal (authenticated consumption).

Drive patterns

Two common patterns can coexist:

• Personal drives: one private drive per account per org (owner_account_id set). This matches “each user gets their own drive in every org they join”.
• Org-owned/shared drives: owner_account_id = NULL, access controlled via org role/policies (and optionally per-drive ACLs).

“Personal orgs” are just orgs with a single member account and a single personal drive.

Authorization checks (high level)

• Org-owned resources: user can access org X iff they have an active accounts row (org_id=X, user_id=U).
• Drive access: user can access drive D iff they’re a member of D.org_id and their role/policies allow the requested operation.